Couper Documentation

edge

Command Line Interface

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

CommandDescription
runStart the server with given configuration file.
helpPrint the usage for the given command: help run
verifyVerify the syntax of the given configuration file.
versionPrint the current version and build information.

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

Basic Options

ArgumentDefaultEnvironmentDescription
-fcouper.hclCOUPER_FILEPath to a Couper configuration file.
-d""COUPER_FILE_DIRECTORYPath to a directory containing Couper configuration files.
-p8080COUPER_DEFAULT_PORTSets the default port to the given value and does not override explicit [host:port] configurations from file.
-e""COUPER_ENVIRONMENTName of environment in which Couper is currently running.
-watchfalseCOUPER_WATCHWatch for configuration file changes and reload on modifications.
-watch-retries5COUPER_WATCH_RETRIESMaximum retry count for configuration reloads which could not bind the configured port.
-watch-retry-delay500msCOUPER_WATCH_RETRY_DELAYDelay duration before next attempt if an error occurs.

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

Note: Couper can be started with multiple -f <file> and -d <dir> arguments.

Files in the -d <dir> are loaded in alphabetical order. Blocks and attributes defined in later files may override those defined earlier. See Merging for details.

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

Example

$ tree.โ”œโ”€โ”€ confโ”‚ โ”œโ”€โ”€ a.hclโ”‚ โ”œโ”€โ”€ b.hclโ”‚ โ””โ”€โ”€ c.hclโ”œโ”€โ”€ devel.hclโ””โ”€โ”€ global.hcl1 directory, 5 files$ couper run -f global.hcl -d conf/ -f devel.hcl -log-level=debugDEBU[0000] loaded files โ€ฆ [โ€ฆ/global.hcl โ€ฆ/conf/a.hcl โ€ฆ/conf/b.hcl โ€ฆ/conf/c.hcl โ€ฆ/devel.hcl] โ€ฆโ€ฆ

Oberservation Options

ArgumentDefaultEnvironment VariableDescription
-health-path/healthzCOUPER_HEALTH_PATHPath for health-check requests for all servers and ports.
-log-formatcommonCOUPER_LOG_FORMATCan be set to json output format. This is the default on containers.
-log-levelinfoCOUPER_LOG_LEVELSet the log-level to one of: info, panic, fatal, error, warn, debug, trace.
-log-prettyfalseCOUPER_LOG_PRETTYOption for json log format which pretty prints with basic key coloring.
-request-id-accept-from-header""COUPER_REQUEST_ID_ACCEPT_FROM_HEADERName of a client request HTTP header field that transports the request.id which Couper takes for logging and transport to the backend (if configured).
-request-id-backend-headerCouper-Request-IDCOUPER_REQUEST_ID_BACKEND_HEADERName of a HTTP header field which Couper uses to transport the request.id to the backend.
-request-id-client-headerCouper-Request-IDCOUPER_REQUEST_ID_CLIENT_HEADERName of a HTTP header field which Couper uses to transport the request.id to the client.
-request-id-formatcommonCOUPER_REQUEST_ID_FORMATIf set to uuid4 a RFC 4122 UUID is used for request.id and related log fields.
-server-timing-headerfalseCOUPER_SERVER_TIMING_HEADERIf enabled, Couper includes an additional Server-Timing HTTP response header field detailing connection and transport relevant metrics for each backend request.
-beta-metricsfalseCOUPER_BETA_METRICSOption to enable the Prometheus metrics exporter.
-beta-metrics-port9090COUPER_BETA_METRICS_PORTPrometheus exporter listen port.
-beta-service-namecouperCOUPER_BETA_SERVICE_NAMEThe service name which applies to the service_name metric labels.

Oberservation Environment Variables

The following environment variables have no corresponding command-line arguments or settings:

Environment VariableDefaultDescription
COUPER_ACCESS_LOG_REQUEST_HEADERSUser-Agent,Accept,RefererA comma separated list of request header names whose values should be logged.
COUPER_ACCESS_LOG_RESPONSE_HEADERSCache-Control,Content-Encoding,Content-Type,LocationA comma separated list of response header names whose values should be logged.
COUPER_ACCESS_LOG_TYPE_VALUEcouper_accessValue for the log field type.
COUPER_BACKEND_LOG_REQUEST_HEADERSUser-Agent, Accept, RefererA comma separated list of request header names whose values should be logged.
COUPER_BACKEND_LOG_RESPONSE_HEADERSCache-Control,Content-Encoding,Content-Type,LocationA comma separated list of response header names whose values should be logged.
COUPER_BACKEND_LOG_TYPE_VALUEcouper_backendValue for the log field type.
COUPER_LOG_PARENT_FIELD""An option for json log format to add all log fields as child properties.
COUPER_LOG_TYPE_VALUEcouper_daemonValue for the runtime log field type.

TLS Options

ArgumentDefaultEnvironment VariableDescription
-ca-file""COUPER_CA_FILEOption for adding the given PEM encoded CA certificate to the existing system certificate pool for all outgoing connections.
-https-dev-proxy""COUPER_HTTPS_DEV_PROXYList of TLS port mappings to define the TLS listen port and the target one. A self-signed certificate will be generated on the fly based on the given hostname.
-secure-cookies""COUPER_SECURE_COOKIESIf set to strip, the Secure flag is removed from all Set-Cookie HTTP header fields.

Profiling Options

ArgumentDefaultEnvironment VariableDescription
-pproffalseCOUPER_PPROFEnables profiling.
-pprof-port6060COUPER_PPROF_PORTPort for profiling interface.

Timing Environment Variables

The following environment variables have no corresponding command-line arguments or settings:

Environment VariableDefaultDescription
COUPER_TIMING_IDLE_TIMEOUT60sThe maximum amount of time to wait for the next request on client connections when keep-alives are enabled.
COUPER_TIMING_READ_HEADER_TIMEOUT10sThe amount of time allowed to read client request headers.
COUPER_TIMING_SHUTDOWN_DELAY0The amount of time the server is marked as unhealthy until calling server close finally.
COUPER_TIMING_SHUTDOWN_TIMEOUT0The maximum amount of time allowed to close the server with all running connections.

Surrounding Architecture Options

ArgumentDefaultEnvironment VariableDescription
-accept-forwarded-url""COUPER_ACCEPT_FORWARDED_URLWhich X-Forwarded-* request headers should be accepted to change the request variables url, origin, protocol, host, port. Comma-separated list of values. Valid values: proto, host, port
-no-proxy-from-envfalseCOUPER_NO_PROXY_FROM_ENVDisables the connect hop to configured proxy via environment.
-xfhfalseCOUPER_XFHGlobal configurations which uses the X-Forwarded-Host header instead of the request host.