Command line

The binary has two commands:

Command	Purpose
nocleye gateway	Run the gateway.
nocleye check	Validate a config file without starting the gateway.

Every flag can also be set with an environment variable. In the tables below, the variable is listed under its flag. A flag takes precedence over its environment variable.

nocleye gateway

nocleye gateway --gConfigPath ./gateway.yaml --gPort 8080

Gateway listener

Flag and variable	Default	Description
--gHost GATEWAY_HOST	0.0.0.0	Address to bind the gateway to.
--gPort GATEWAY_PORT	8080	Port to bind the gateway to.
--gConfigPath GATEWAY_CONFIG_PATH	none	Path to the config file. Required.
--gShutdownTimeout GATEWAY_SHUTDOWN_TIMEOUT	10s	Maximum time to wait for requests in flight on shutdown, e.g. 15s.
--gTrustedProxies	none	Comma separated IPs or CIDRs of load balancers/CDNs allowed to set X-Forwarded-For. Leave empty when the gateway is the first hop.

When --gTrustedProxies is empty, the caller IP is always the address of the connection. Only set it to the proxies you control, otherwise callers can fake their IP and escape usage control.

TLS

Flag and variable	Default	Description
--gTLSEnabled GATEWAY_TLS_ENABLED	false	Terminate TLS on the gateway listener.
--gTLSCert GATEWAY_TLS_CERT	none	Path to the certificate file.
--gTLSKey GATEWAY_TLS_KEY	none	Path to the private key file.

Certificate rotation is detected automatically.

Logs

Flag and variable	Default	Description
--gLogLevel GATEWAY_LOG_LEVEL	info	trace, debug, info, warn or error.
--gLogFormat GATEWAY_LOG_FORMAT	json	json or console.
--gAccessLogSinks GATEWAY_ACCESS_LOG_SINKS	stdout	stdout writes the access log to standard output, none turns it off. Changing it requires a restart.

See Logs and metrics.

Support server

An internal server for health probes, metrics and the live config API. Bind it to a private address, it is not meant to be public.

Flag and variable	Default	Description
--sHost SUPPORT_HOST	127.0.0.1	Address to bind the support server to. Use 0.0.0.0 inside a container that doesn’t publish the port.
--sPort SUPPORT_PORT	8081	Port of the support server. Must differ from --gPort.
--sToken SUPPORT_TOKEN	none	Bearer token required by the live config API. Never logged.
--sPrometheusEnabled SUPPORT_PROMETHEUS_ENABLED	false	Serve /metrics and record Prometheus metrics.
--sPrometheusMetrics SUPPORT_PROMETHEUS_METRICS	none	Comma separated metric families to expose, or all. Empty exposes none.
--sPrometheusMaxSeries SUPPORT_PROMETHEUS_MAX_SERIES	20000	Cap on the label combinations of gw_requests_total.

See Support server and Logs and metrics.

nocleye check

nocleye check --gConfigPath ./gateway.yaml

Reads the config file and reports what is wrong with it, without starting the gateway. Run it in CI or before every deploy.

It takes the same --gConfigPath, --gHost, --gPort, --sHost, --sPort, --sToken, --sPrometheusEnabled, --sPrometheusMetrics and --sPrometheusMaxSeries flags, with the same environment variables and defaults as nocleye gateway. Pass the values you will run the gateway with, so the flags are validated too.

What it checks

• The structure and values of the config file: unknown keys, wrong value types, unknown modes, references to rules, servers and authentication methods that don’t exist, invalid URLs and time windows, and so on.
• The support server flags: the support port must differ from the gateway port, and the list given to --sPrometheusMetrics must contain known metric families.
• That the TLS CA file of a server (TLS.CACertFile) exists and contains a valid certificate.

It does not read the authentication key files (KeyRef) or contact the backends, those are checked when the gateway starts.

Every problem found is listed with where it is and how to fix it, errors first, then warnings. See the check reference for the full list.

Checking gateway.yaml

ERRORS (1)
  1. Route targets a server that doesn't exist
     Where: route checkout, server checkut
     Fix:   Set TargetServer to a name defined under ServerConfigs.

WARNINGS (1)
  1. No auth method defined
     Fix:   Add an entry under AuthMethods if you need protection.

✗ 1 error, 1 warning. The gateway will not start with this config.

• Errors stop the gateway from starting.
• Warnings don’t stop it from starting, but point to a likely mistake or a risky setup.

Exit code

nocleye check exits with success whenever the check ran, even if the config has errors, so read the report. It exits with a failure only when no config file was given, the file can’t be read, or on an internal failure.

Colors are used when the output is a terminal. Set NO_COLOR to turn them off.