Skip to content

Configuration reference

FastMock is configured only through environment variables. They are read once at start-up; nothing that affects security (tokens, origins, egress policy, secrets, storage, listeners) can be changed through the admin API.

The Helm chart and the operator set most of these variables for you; see Helm chart and Operator for the mapping.

Value formats

Type Format Examples
string as is; an empty or whitespace-only value counts as unset fastmock:
list items separated by commas or new lines; blanks are ignored a,b, "a\nb"
boolean 1, true, yes, on / 0, false, no, off (any case) true
duration an integer followed by ms, s, m, h or d; no unit means seconds 250ms, 30s, 15m, 24h, 7d, 2
bytes an integer number of bytes 10485760
address host:port socket address (an IP, not a host name) 0.0.0.0:8080, [::]:8080

An invalid value stops the server at start-up with a message that names the variable, for example FASTMOCK_CALLBACK_TIMEOUT: invalid duration unityin5y``.

Listeners and storage

Variable Type Default Effect
FASTMOCK_LISTEN address 0.0.0.0:8080 Data plane: the port that serves mocks (HTTP/1.1, h2c, HTTPS with HTTP/2 when TLS is configured, gRPC, SSE, plugins).
FASTMOCK_ADMIN_LISTEN address 0.0.0.0:9090 Control plane: admin API, UI, /metrics, /healthz, /readyz. Must differ from FASTMOCK_LISTEN; the server refuses to start otherwise.
FASTMOCK_STORAGE postgres | memory postgres memory keeps everything in the process (one instance, development and CI). postgres stores stubs, journal, callbacks, audit and data in PostgreSQL and hot state in Valkey, so replicas share everything. See Concepts: storage.
FASTMOCK_DATABASE_URL URL none, required for postgres PostgreSQL connection URL, for example postgres://fastmock@db.example.com:5432/fastmock?sslmode=verify-full. Migrations run automatically at start-up.
FASTMOCK_DATABASE_PASSWORD string none Password added to FASTMOCK_DATABASE_URL with correct URL encoding. Use it to keep the password out of the URL (for example from a separate Secret key).
FASTMOCK_DB_MAX_CONNECTIONS integer 10 Size of the PostgreSQL connection pool per replica.
FASTMOCK_VALKEY_URL URL none, required for postgres Valkey (or any Redis-protocol server) URL, for example redis://valkey.example.com:6379/. Plain TCP; run Valkey in the same trusted network or behind a TLS-terminating sidecar.
FASTMOCK_VALKEY_PASSWORD string none Password added to FASTMOCK_VALKEY_URL with correct URL encoding.
FASTMOCK_VALKEY_PREFIX string fastmock: Prefix of every Valkey key. Give each FastMock instance that shares a Valkey database its own prefix (the operator uses fastmock:<name>:).
FASTMOCK_STUB_POLL duration 5s Interval of the maintenance loop: reloads stubs when their revision changed (PostgreSQL LISTEN/NOTIFY normally reloads them at once, polling is the fallback), refreshes gRPC descriptors, updates the fastmock_stubs_loaded and fastmock_callbacks_pending gauges, and once a minute applies retention.

fastmock migrate applies the database migrations and exits; it needs only FASTMOCK_DATABASE_URL.

Admin authentication

Variable Type Default Effect
FASTMOCK_ADMIN_TOKENS list none Admin tokens as name:role:sha256hex entries. name is letters, digits, -, _, ., @; role is viewer, editor or admin; the hash is the hex SHA-256 of the token (fastmock hash-token).
FASTMOCK_ADMIN_TOKENS_FILE path none File with one name:role:sha256hex entry per line; blank lines and lines starting with # are ignored. Entries from the file and from FASTMOCK_ADMIN_TOKENS are combined.
FASTMOCK_AUTH_DISABLED boolean false Turns admin authentication off: every caller becomes anonymous with the admin role and the same-origin exception for browsers is disabled. For a developer laptop only; the server logs a warning at start-up. The operator refuses this variable in MockServer.spec.env.
FASTMOCK_ADMIN_ALLOWED_ORIGINS list none Browser origins (exact scheme://host[:port]) allowed to call the admin port, for example https://fastmock-admin.example.com. Requests without an Origin header (curl, test clients) are not affected. A request whose Origin equals http(s):// plus its own Host header is also accepted while authentication is enabled. Anything else gets 403 {"error":"origin not allowed","details":[]}.
Variable Type Default Effect
FASTMOCK_UI_ENABLED boolean true false, 0, no or off switches the web UI off: /ui and everything below it answer 404. The admin API, /openapi.json and /metrics are not affected. See Web UI.
FASTMOCK_UI_DATA_PLANE_URL list none Exact origins (scheme://host[:port], no path, no wildcard) of the data plane as browsers reach it, for example https://mock.example.com. The UI's Content-Security-Policy allows connect-src to 'self' and these origins only, and the first one is the default target of the test-request panel. Without it, connect-src allows 'self' and the data port on the host name the browser used for the UI (http(s)://<ui host>:<FASTMOCK_LISTEN port>). An invalid entry is a start-up error.

The server does not start without at least one token unless FASTMOCK_AUTH_DISABLED=true. Roles and token handling are described in Security.

Data-plane TLS and mTLS

Variable Type Default Effect
FASTMOCK_TLS_CERT_FILE path none PEM certificate chain for the data port. Set together with FASTMOCK_TLS_KEY_FILE; setting only one of them is a start-up error. With TLS the data port negotiates HTTP/2 or HTTP/1.1 through ALPN.
FASTMOCK_TLS_KEY_FILE path none PEM private key.
FASTMOCK_TLS_CLIENT_CA_FILE path none PEM bundle of CAs that client certificates must chain to. Enables mTLS.
FASTMOCK_TLS_CLIENT_AUTH required | optional required With a client CA: required rejects handshakes without a valid client certificate, optional accepts them but still verifies any certificate that is presented.

When a client certificate was verified, the data plane adds the request header x-fastmock-client-cert-sha256 (lower-case hex SHA-256 of the DER certificate) so stubs can match on the caller's identity; a header with that name sent by the client is always removed first. The admin port is plain HTTP; terminate TLS for it at the Gateway or ingress (see Helm: TLS).

Request limits and timeouts

Variable Type Default Effect
FASTMOCK_MAX_BODY_BYTES bytes 10485760 (10 MiB) Largest request body on the data port. Larger requests get 413 {"error":"request body too large"} (checked against Content-Length before reading, and while reading chunked bodies).
FASTMOCK_MAX_INFLIGHT_BODY_BYTES bytes 268435456 (256 MiB) Memory budget for request bodies being processed at the same time. Each request reserves three times its Content-Length (or three times FASTMOCK_MAX_BODY_BYTES when the length is unknown). A request that cannot get its share within 10 seconds gets 503 {"error":"server busy: too many large requests in flight"} with Retry-After: 1. Must be at least FASTMOCK_MAX_BODY_BYTES.
FASTMOCK_MAX_DELAY duration 15m Upper bound for response delay, chaos delays and SSE event delays. Callback delays have their own limit of 7 days.
FASTMOCK_HEADER_READ_TIMEOUT duration 30s Time an HTTP/1.1 client has to send the complete request headers on either port.
FASTMOCK_SHUTDOWN_DELAY duration 5s After SIGTERM or Ctrl-C: /readyz starts returning 503 at once, the listeners stay open for this long so load balancers can stop sending traffic, then open connections get up to 20 seconds to finish.
FASTMOCK_RECORDING_MAX_STUBS integer 1000 Number of stubs one recording session may create; further new exchanges are proxied but not stored (fastmock_recording_skipped_total{reason="limit"}).
FASTMOCK_JOURNAL_SCAN_TIMEOUT duration 10s Deadline of one journal scan (POST /__admin/requests/find, /requests/remove, /verify, /verify/sequence, /requests/count, /requests/near-misses). A scan that runs longer is stopped and answers 503. Scans run on the blocking thread pool, never on the request-handling threads, and stop as soon as the client disconnects.
FASTMOCK_JOURNAL_SCAN_MAX_WORK integer 4294967296 Work budget of one scan: the sum, over scanned journal entries, of the entry size in bytes (body, path, query and headers plus 64) times the weight of the pattern (number of matchers plus 1 per KiB of pattern JSON). A scan that would exceed it stops and answers 422.
FASTMOCK_JOURNAL_SCAN_CONCURRENCY integer 2 Scans that run at the same time per replica (minimum 1). A scan that does not get a slot within 5 seconds answers 503.
FASTMOCK_UNMATCHED_DETAILS boolean false Adds nearMisses (the three closest stubs and why they did not match) to the 404 body of unmatched data-plane requests. Off by default because it reveals stub definitions to callers of the data port; the same information is always available to viewers through POST /__admin/requests/near-misses.

Request journal

Variable Type Default Effect
FASTMOCK_JOURNAL_ENABLED boolean true Record data-plane requests and responses.
FASTMOCK_JOURNAL_RETENTION duration 24h Entries older than this are deleted (checked once a minute). In memory mode the journal also keeps at most the latest 100,000 entries.
FASTMOCK_JOURNAL_MAX_BODY_BYTES bytes 65536 Request and response bodies are stored up to this size and marked …[truncated N bytes] beyond it. Also limits the bodies shown by GET /__admin/callbacks.
FASTMOCK_JOURNAL_QUEUE integer 2048 Entries waiting to be written. The journal is written in the background after the response; when the queue is full, entries are dropped and counted in fastmock_journal_dropped_total.
FASTMOCK_REDACT_HEADERS list see below Header names (case-insensitive) whose values are masked as *** (an Authorization-style scheme such as Bearer is kept). Replaces the default list.
FASTMOCK_REDACT_JSON_KEYS list see below Field names masked in JSON, form, XML and multipart bodies and in query strings. Matching ignores case, - and _. Replaces the default list.

Default FASTMOCK_REDACT_HEADERS: authorization, proxy-authorization, cookie, set-cookie, x-api-key, apikey, api-key, x-auth-token, x-callback-token, x-goog-signature, x-signature, x-hub-signature, x-hub-signature-256, sha2-signature, ocp-apim-subscription-key, x-amz-security-token, x-fastmock-signature. In addition, any header whose name contains one of the words sig, signature, hmac, token, secret, password, apikey, key, credential(s) (split on - and _), or ends with signature or token, is always masked.

Default FASTMOCK_REDACT_JSON_KEYS: password, passwd, secret, token, access_token, refresh_token, id_token, client_secret, otp, apikey, api_key, authorization, auth, pin, cvv, sig, signature, key, private_key, session.

Redaction applies to what FastMock stores and shows (journal, callbacks API, logs, UI). Matching and templates always see the original request. See Security: redaction.

Callbacks and outgoing traffic

Variable Type Default Effect
FASTMOCK_CALLBACK_WORKERS integer 32 Callbacks delivered at the same time per replica (minimum 1).
FASTMOCK_CALLBACK_BATCH integer 50 Most callbacks claimed from the outbox in one poll (minimum 1).
FASTMOCK_CALLBACK_POLL duration 200ms How often each replica looks for due callbacks.
FASTMOCK_CALLBACK_TIMEOUT duration 10s Timeout of one delivery attempt (connect timeout is the smaller of this and 5 s). A claimed callback is leased for twice this value plus 5 s; if a replica stops during delivery, another replica retries after the lease expires. Proxy stubs and recording use the same client with a 30-second request timeout.
FASTMOCK_CALLBACK_RETENTION duration 24h Delivered and failed callbacks older than this are deleted. Pending callbacks are kept.
FASTMOCK_CALLBACK_ALLOWED_HOSTS list none (any host) Host allow-list for callbacks, proxy stubs and recording: exact names (hooks.example.com) or suffixes (*.svc.cluster.local, which matches a.svc.cluster.local but not svc.cluster.local).
FASTMOCK_CALLBACK_DENIED_CIDRS list see below Address ranges that callbacks, proxy stubs and recording never connect to. Checked on literal IPs in the URL and on every address the host name resolves to. Replaces the default list.
FASTMOCK_OUTBOUND_CA_FILE path unset PEM bundle of extra CA certificates trusted for outgoing HTTPS (callbacks, proxy stubs, recording, contract tests), in addition to the built-in public roots. Startup fails if the file is missing or holds no certificate.
FASTMOCK_STUB_SECRETS list none Names of secrets that stubs may reference in callbacks[].hmac.secretRef. Any other name fails the callback with secret ... is not configured. Plugins have their own secrets and are not limited by this list. These secrets can never be sent by contract tests.
FASTMOCK_CONTRACT_SECRETS list none Secrets that contract tests may send in secretHeaders, each bound to the hosts that may receive it: name=host1\|host2, for example petstore-token=petstore.example.com\|*.petstore.example.com. Hosts are exact names or IP addresses, or *.suffix for subdomains. A name may not also appear in FASTMOCK_STUB_SECRETS; a malformed entry is a start-up error. Starting a run with secretHeaders needs the admin role. See Contract testing: secrets.

Default FASTMOCK_CALLBACK_DENIED_CIDRS: 127.0.0.0/8, ::1/128, ::/128, ::ffff:127.0.0.0/104, ::ffff:169.254.0.0/112, ::ffff:0.0.0.0/104, 169.254.0.0/16, fe80::/10, fd00:ec2::254/128, 100.100.100.200/32, 0.0.0.0/8, 224.0.0.0/4, ff00::/8 (loopback, link-local including cloud metadata endpoints, unspecified and multicast). Unspecified and multicast addresses are refused even if you replace the list, and IPv4 addresses embedded in IPv6 (IPv4-mapped, NAT64 64:ff9b::/96, 6to4 2002::/16, IPv4-compatible) are checked as IPv4. Private ranges such as 10.0.0.0/8 are allowed by default because callbacks usually go to services in the same cluster; use FASTMOCK_CALLBACK_ALLOWED_HOSTS to narrow them.

Outgoing requests never follow redirects, never use an HTTP proxy from the environment, and refuse URLs with credentials or schemes other than http and https. Callbacks, proxy stubs and contract tests never send Host, hop-by-hop or forwarding headers taken from stubs, from the proxied client request or from a run request (the list is in Contract testing); stubs that set them in proxy.additionalHeaders or callbacks[].headers are rejected with 400. Details: Callbacks, Security: egress.

Secrets

Variable Type Default Effect
FASTMOCK_SECRETS_DIR path none Directory with one file per secret (file name = secret name, content = value; trailing new lines are removed). Typically a mounted Kubernetes Secret.
FASTMOCK_SECRET_<NAME> string none A secret given directly. The name is upper-cased with - and . replaced by _: secret delivery-hook is FASTMOCK_SECRET_DELIVERY_HOOK. Takes precedence over the file.

Secret names are 1 to 128 characters of letters, digits, -, _ and . and do not start with .. Secrets are used for HMAC signatures (FASTMOCK_STUB_SECRETS), by contract tests (FASTMOCK_CONTRACT_SECRETS) and by plugins; templates cannot read them.

Kafka

Variable Type Default Effect
FASTMOCK_KAFKA_BOOTSTRAP list none Kafka bootstrap servers (host:port) for stub messages. Without it, stubs with messages still respond, but publishing fails and is counted as fastmock_messages_total{result="failed"}.
FASTMOCK_KAFKA_SCHEMA_REGISTRY_URL URL none Confluent-compatible Schema Registry (http:// or https://), required for messages with avroSchema.
FASTMOCK_KAFKA_ALLOWED_TOPICS list none (any topic) Topics stub messages may publish to: exact names or prefixes ending in * (orders.*). It does not grant reading.
FASTMOCK_KAFKA_CONTRACT_TOPICS list none (reading disabled) Topics AsyncAPI contract tests may read: exact names or prefixes ending in *. A prefix entry never matches internal topics starting with _ unless the prefix starts with _. Without it, AsyncAPI contract tests answer 400.

See Kafka messages.

Plugins

Variable Type Default Effect
FASTMOCK_PLUGINS list all compiled-in plugins Plugins to enable; all enables every plugin. fastmock plugins lists what the binary contains.
FASTMOCK_PLUGIN_<PLUGIN>_<KEY> string none Setting <key> of plugin <plugin> (both upper-cased, - becomes _); the plugin sees the key in lower case.

Each plugin is mounted on the data port under /<name> and may add admin routes under /__admin/plugins/<name>/. Plugin-specific settings are documented with the plugins; see Writing plugins.

Logging and telemetry

Variable Type Default Effect
FASTMOCK_LOG_FORMAT json | text json Log format on stdout.
RUST_LOG filter info,sqlx=warn,hyper=warn,h2=warn,reqwest=warn,opentelemetry=warn Log levels per module, for example info,fastmock_server::outbox=debug. Audit records use the target audit.
OTEL_EXPORTER_OTLP_ENDPOINT URL none Enables OpenTelemetry export of traces and logs over OTLP/HTTP (protobuf), for example http://otel-collector:4318. Without an endpoint nothing is exported.
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, OTEL_EXPORTER_OTLP_LOGS_ENDPOINT URL none Per-signal endpoints; setting either also enables export.
OTEL_SERVICE_NAME string fastmock service.name resource attribute.
OTEL_SDK_DISABLED boolean false true disables export even when an endpoint is set.

Other standard OpenTelemetry SDK variables (such as OTEL_EXPORTER_OTLP_HEADERS and OTEL_RESOURCE_ATTRIBUTES) are read by the SDK. Prometheus metrics are always available on /metrics. See Observability.

Command line

fastmock serve            run the server (the default command)
fastmock migrate          apply PostgreSQL migrations and exit (needs FASTMOCK_DATABASE_URL)
fastmock hash-token       print the SHA-256 of a token read from the argument or stdin
fastmock hash-token --generate   generate a new random token and print it with its hash
fastmock validate FILE    validate a stub, a list of stubs or {"stubs": [...]} without a server
fastmock plugins          list compiled-in plugins
fastmock --version

Build-time variable: FASTMOCK_GIT_SHA, when set during cargo build, is embedded into the binary and reported by GET /__admin/version as gitSha.

Operator settings

The operator (fastmock-operator) reads these variables; the operator chart sets them.

Variable Default Effect
FASTMOCK_OPERATOR_NAMESPACE empty (all namespaces) Watch only this namespace.
FASTMOCK_OPERATOR_SERVER_IMAGE fastmock:<operator version> Image used when a MockServer does not set spec.image.
FASTMOCK_OPERATOR_ALLOWED_IMAGE_PREFIXES the repository of the default image Comma-separated image prefixes a MockServer may use.
FASTMOCK_OPERATOR_ADMIN_URL_TEMPLATE http://{name}-admin.{namespace}.svc:9090 How the operator reaches a server's admin API.
FASTMOCK_OPERATOR_LISTEN 0.0.0.0:8081 Operator /healthz, /readyz and /metrics.
RUST_LOG info,kube=warn,hyper=warn Operator log levels.