Configuration Reference

Controls whether the HTTPS connector for the GUI is enabled.

Values:

• true - Creates an HTTPS server connector on the specified HTTPS port
• false - No HTTPS connector is created; GUI is not accessible via HTTPS

Specifies the path to the Java KeyStore (JKS) file containing the SSL/TLS certificate for HTTPS connections to the GUI.

Note: The path is relative to the Traffic Parrot installation directory or can be an absolute path.

The password for the JKS keystore file specified in trafficparrot.gui.https.jks.resource.

Security Note: In test and development environments, use a strong password and consider using environment variables or secure credential stores.

Controls the authentication mode for the GUI.

Values:

• ALLOW_ALL - No authentication required (default)
• LOGIN_PROPERTIES - Uses basic HTTP authentication with credentials from trafficparrot.gui.login.properties file. The log pages that every virtual service HTTP and HTTPS port serves under /__logs (/__logs/virtualservice/ and /__logs/access/, a scenario's own ports included) ask for the same login. Read them through the Logs page or the HTTPS port: a plain-HTTP port sends the password unencrypted. Stubs and the admin API on those ports are not affected.

Security Note: For test and development environments, it's recommended to use LOGIN_PROPERTIES mode with HTTPS enabled.

Master switch to enable or disable the GUI entirely.

Values:

• true - GUI server starts normally
• false - GUI server won't start (useful for headless/API-only deployments)

When enabled, requests made to the GUI port that don't match GUI endpoints will be forwarded to the simulator (virtual service/mock) port.

Use Case: This allows the GUI and simulator (virtual service/mock) to effectively share the same port, simplifying configuration in some scenarios.

Note: In performance profile, this is disabled by default to maximize throughput.

Controls whether JMX (Java Management Extensions) is enabled for the GUI server.

Use Case: Enable this for remote monitoring and management of the GUI server using JMX tools.

The port number for JMX connections when JMX is enabled.

Valid Range: 1-65535

Note: Only effective when trafficparrot.gui.jmx.enabled is set to true.

The maximum time in milliseconds to wait for the GUI server to start up before timing out.

Default: 45000 (45 seconds)

Use Case: Increase this value if the GUI server takes longer to start on slower systems or when loading large configurations.

Maximum number of threads in the Jetty thread pool for handling GUI HTTP requests.

Performance Note: This affects the GUI server's ability to handle concurrent connections. Increase for high-concurrency scenarios.

Resource Impact: Each thread consumes memory, so balance this with available system resources.

Sets the minimum number of threads in the Jetty thread pool for the Traffic Parrot GUI HTTP server.

Performance Impact: Controls the base number of threads available for handling GUI requests. Higher values ensure better responsiveness under load.

Comma-separated list of regex patterns for the files the GUI configuration files editor (Settings, Current configuration files) lists, loads and saves, matched against each file's path under the Traffic Parrot installation directory and the traffic files directory, as trafficparrot.gui.config.files.notAllowedFilesToEdit below is. A file this list allows and that list matches is not offered.

The shipped list allows .json, .csv and .properties files and .hbs files, so a Handlebars partial that a response template includes (see Template files) can be edited on the page, and the next response that includes it uses the edit, with no restart. Partials also have a page of their own, Tools, Templates, which lists the .hbs files under the traffic files directory and loads and saves them the same way, so this list governs that page too. A partial with another extension is listed only if its suffix is in the list. The editor keeps an LF-only file's line breaks: a file that uses LF alone is saved with LF, and a file with CRLF or mixed line breaks, a file with no line break, and a new file are saved with CRLF. An installation that overrides this property keeps its own list, so add .hbs$ to it to edit partials on either page.

Security: Keeps files the editor has no business with out of it. The credential files are kept out by trafficparrot.gui.config.files.notAllowedFilesToEdit, and loading and saving need traffic-parrot-gui-edit-role when the web user interface login is on.

Comma-separated (CSV) list of regex patterns for files and directories that the GUI configuration files editor will neither load nor save. The list gates Load as well as Save, so a file it matches cannot be read through the editor either. Each pattern is matched against the file's path relative to the Traffic Parrot installation directory or the traffic files directory, so a pattern cannot be triggered by a directory name further up the machine's filesystem. Override this property to change the list; an installation that does so keeps its own list, so carry the entries described below into it.

By default, the first pattern ^\. matches a dot-prefixed directory or file in the first path segment below that directory (for example .idea, .vscode, or .claude sitting directly under the traffic files directory), so those hidden entries are blocked from editing in addition to the listed build and system directories (target, deleted-scenarios, trafficparrot.properties, trafficparrot.performance.properties, log4j, lib) and the three credential entries described below. A dot-prefixed directory nested deeper (for example mappings/.hidden) is not matched by this pattern; add /\. to the list if you want dot-entries blocked at any depth. .git has its own entry and so is blocked at any depth. A dot inside a file name is not affected, so report.v1.json stays editable.

Three entries keep files that hold credentials out of the editor. trafficparrot.gui.login.properties is the web user interface's own user store, which holds every user name, password and role when trafficparrot.gui.security.mode=LOGIN_PROPERTIES is set. .*-connections\.json matches database-connections.json, ibm-mq-connections.json, jms-connections.json and any other file whose path contains -connections.json: the files that hold the connection details and passwords for the databases, IBM MQ queue managers and JMS brokers Traffic Parrot connects to. sftp-server-users\.json matches the embedded SFTP server's users file under its default name, which holds each user's password or authorized keys. Each entry keeps the file it names out of the editor and nothing more. Whatever this list says, that users file and the server's host key are also refused under the names trafficparrot.file.sftp.server.usersFile and trafficparrot.file.sftp.server.hostKeyFile give them, whether or not the server is enabled. The list is not a permission check on the user: any other file the editor lists (see trafficparrot.gui.config.files.allowedFilesToEdit) can be loaded and saved by every user who holds traffic-parrot-gui-edit-role, whatever it holds, including a connections file whose path does not contain -connections.json. When trafficparrot.gui.security.mode=LOGIN_PROPERTIES is set, a signed-in user without that role sees the file names only, and the /api/configuration/files endpoints that load or save a file refuse that user with 403; with the default ALLOW_ALL nobody signs in, so every user can load and save.

Security: Blocks access to system-critical files and directories.

How requests to /mcp are authenticated.

ALLOW_LOCAL_HOST_ONLY (the default) accepts requests from this machine only, and needs no token.

BEARER_TOKEN accepts requests from anywhere, and every one must carry an Authorization: Bearer <token> header matching trafficparrot.mcp.token.

Use Case: BEARER_TOKEN is what you need when the assistant is not where Traffic Parrot is: notably Traffic Parrot in a container with a published port, where requests arrive from the container network rather than from loopback, and ALLOW_LOCAL_HOST_ONLY therefore refuses them.

The bearer token that a request to /mcp must carry.

Required when trafficparrot.mcp.authenticator=BEARER_TOKEN; Traffic Parrot will not start without it. Ignored otherwise.

Security: Choose your own secret. There is no default, deliberately: a shipped default token would be a published one.

Web origins allowed to drive /mcp from a browser: a comma-separated list, each entry scheme://host or scheme://host:port, matched without regard to case.

A request that carries an Origin header naming any other origin is refused with HTTP 403 and JSON-RPC error -32002, whichever authenticator is in use. Only a browser sends that header, so an assistant that speaks HTTP directly is unaffected, and the empty default refuses every browser-hosted client until you name its origin. See From a browser.

Security: The check stops a page you are visiting from reaching /mcp by making its own hostname resolve to 127.0.0.1 (DNS rebinding). List only origins you serve yourself: an entry admits every page that origin serves.

Controls whether gzipped responses are uncompressed before saving to disk during recording.

Impact: When enabled, makes recorded traffic files more readable but may increase disk usage.

Enables automatic following of HTTP redirects during recording.

Use Case: When enabled, Traffic Parrot will follow redirect chains automatically during proxy recording.

See Handling HTTP redirects during recording for the full behaviour and a comparison of the enabled and disabled modes.

Filters recording to only capture specific content types.

Default: TP_RECORD_ALL_CONTENT_TYPES (special value meaning record all)

Example: application/javascript,application/xml to record only JS and XML content

Regex patterns applied to response bodies during recording, rewriting the content as the client sees it before it is matched and saved.

Format: pattern->replacement,pattern2->replacement2

Example: https://api\.example\.com->http://localhost:8081 rewrites a production host to your local simulator host.

Use Case: Transform production URLs to test environment URLs in recorded responses. Paired with trafficparrot.http.recording.storage.rewrite.regex for the on-disk transformation.

A malformed rule stops Traffic Parrot from starting, naming the rule at fault. A rule that was dropped instead would be discovered only by finding the un-rewritten value in a recording.

Regex patterns applied when saving response bodies to disk during recording. Unlike the response rewrite, this transformation is intended to preserve Handlebars templates, so it typically runs in the opposite direction.

This property applies to the response body only. To rewrite recorded request bodies, use trafficparrot.http.recording.request.storage.rewrite.regex below.

Format: pattern->replacement,pattern2->replacement2

Example: http://localhost:8081->http://{{request.requestLine.host}} stores a templated host so the saved mapping replays against whatever host the request arrives on.

Use Case: Keep recorded files environment-agnostic by templating host-specific values as they are written to disk.

A malformed rule stops Traffic Parrot from starting, naming the rule at fault, as for trafficparrot.http.recording.response.rewrite.regex.

Regex patterns applied when saving request bodies to disk during recording. Empty by default, so nothing is rewritten unless you configure it.

Format: pattern->replacement,pattern2->replacement2

Example: ("apiKey"\\s*:\\s*")[^"]*->$1***REDACTED*** replaces the value of a JSON apiKey field with a placeholder, so the real key is never written to a traffic file. The per-request entry in the log shows the rewritten body too, whether or not a recording is running. The backslashes are doubled because trafficparrot.properties is a Java properties file, in which a single \s or \d is read as a bare s or d.

Use Case: Keep credentials, tokens and personal data out of recorded traffic files.

This changes the saved request matcher. The recorded request body is what the matcher is built from, so a replay client sending the real value will no longer match the saved stub. See Rewriting request bodies during recording for the two ways to handle that, and for which content types are covered.

A malformed rule stops Traffic Parrot from starting, naming the rule at fault. This property exists to keep values out of recordings, so a rule that cannot be parsed must not be skipped silently.

Masks credential headers in what recording saves to disk: the recorded response headers, and the request headers recording matches on. Takes true or false; any other value stops Traffic Parrot from starting.

While it is on, Authorization, Cookie, Set-Cookie and Proxy-Authorization are always covered, plus any header named in trafficparrot.http.recording.redaction.headers. The client recording through Traffic Parrot still receives the backend's real headers, and a mapping created in the web user interface or through the admin API is saved as written.

A request header is saved only if it is listed in Record request headers for matching on the Record page, and it is the saved matcher that is redacted: under PLACEHOLDER it expects the placeholder, so a replayed request carrying the real value no longer matches; under DROP the header is not matched at all. See Redacting credential headers during recording for what is and is not covered.

The per-request entry in the log shows the request and response headers of each exchange redacted the same way, whether or not a recording is running. The URL, and the body unless trafficparrot.http.recording.request.storage.rewrite.regex is set, are logged as received.

Set it in trafficparrot.properties, or as a -D system property or a key=value argument to the start script; an override applies whether or not the file holds the key. The same holds for the three properties below.

What redaction does to a covered header. PLACEHOLDER keeps the header and replaces its value with trafficparrot.http.recording.redaction.placeholder; DROP leaves the header out of the saved mapping altogether. Any other value stops Traffic Parrot from starting.

Use Case: Choose DROP when replay clients send the real credential, because a request matcher that expects the placeholder no longer matches them; choose PLACEHOLDER to keep a visible record in the mapping that the header was there.

The value written in place of a covered header's value under the PLACEHOLDER strategy, in the recorded response headers and in the saved request matcher alike.

Header names to redact in addition to Authorization, Cookie, Set-Cookie and Proxy-Authorization, separated by commas or spaces and matched without regard to case. Empty by default. An entry that is not a header name stops Traffic Parrot from starting.

Example: X-Api-Key, X-Session-Token

Sets the default state of the Keep valid-JSON response body inline checkbox in the Advanced parameters section of the HTTP Record page.

Impact: When the checkbox is ticked for a recording session, a response body that is valid JSON served with a text content type is kept inline in the mapping (as a structured jsonBody) instead of being written to a separate __files/ body file; non-JSON and binary bodies are still externalised. There is no size limit, so a very large JSON response is embedded directly in the mapping file.

This property only seeds the checkbox's initial state; the checkbox on the Record page overrides it for that session.

See Keeping JSON response bodies inline for the full behaviour.

Sets the default state of the Externalise request body to file checkbox in the Advanced parameters section of the HTTP Record page.

Impact: When the checkbox is ticked for a recording session, a recorded request body is written to a separate __files/ file and the mapping's request matcher references it by bodyFileName (using equalToJson, equalToXml, binaryEqualTo or equalTo according to the content type) instead of being stored inline as a bodyPatterns value. Empty and multipart request bodies are always kept inline.

This property only seeds the checkbox's initial state; the checkbox on the Record page overrides it for that session.

See Externalising request bodies to files for the full behaviour.

Enables/disables gzip compression of HTTP responses from the simulator (virtual service/mock).

Performance: Reduces bandwidth usage but increases CPU usage for compression.

Cache duration for stub mappings in milliseconds.

Performance: Performance profile uses 10,000,000 ms. Caching reduces file I/O but uses more memory.

Default: 0 (no caching)

Maximum number of entries in the Handlebars template cache.

Performance: Performance profile uses 10,000. Caching improves template rendering speed but uses memory.

Default: 0 (no caching)

Enables indexing and caching of CSV files used in Handlebars select helpers.

Performance: Performance profile enables this. Significantly improves performance when using CSV data in templates.

Controls parameter normalization in Handlebars helpers.

Impact: Affects how helper parameters are processed and validated.

Selects the implementation for the {{now}} helper.

Values:

• WIREMOCK - Uses WireMock version of {{now}} helper
• HANDLEBARS - Uses Handlebars.java version of {{now}} helper

Allows runtime specification of the {{now}} provider.

Usage: When true, allows {{now provider='WIREMOCK'}} syntax in templates.

Controls whether Handlebars helper errors cause request failures or embed inline error strings in responses.

Values:

• false (default) - Errors are embedded as {{ helperName ERROR: message }} in the response body
• true - Errors throw exceptions, resulting in HTTP 500 or messaging failures

Use Case: Enable in CI/CD pipelines and contract testing to make template errors visible as test failures. See Error handling.

HTTP status code returned when no mapping is found for a request.

Use Case: Custom error code to distinguish between unmapped requests and real HTTP errors.

Threshold (0.0-1.0) for determining if content is mostly printable characters.

Default: 0.95 (95% of characters must be printable)

Use Case: Used for message body analysis and logging decisions.

Comma-separated list of JMS properties to skip during recording.

Use Case: Excludes system-generated or time-sensitive properties from recorded JMS messages.

Upgrading: JMS_IBM_MsgToken is in the default because the IBM® MQ 10 client adds it to every message it receives and refuses to set it again, so replaying a recording that kept it sends the response without it and logs a WARN every time. The upgrade command keeps the list your installation already has, so if you record through an IBM MQ 10 client, add JMS_IBM_MsgToken to it yourself.

IBM MQ connection options for queue access operations.

IBM MQ Flags: Controls how queues are opened for input (consumer) operations. Use MQOO_INPUT_EXCLUSIVE for exclusive access to a queue.

IBM MQ connection options for queue access operations.

IBM MQ Flags: Controls how queues are opened for output (producer) operations.

Master switch that controls whether the WebSocket simulator starts.

Values:

• false (default) - WebSocket upgrade requests are not accepted.
• true - WebSocket clients can connect to the main virtual service HTTP port using Connection: Upgrade, and mappings are loaded from websocket-mappings/ in the selected scenario, or at the traffic files root when no scenario is selected.

Controls how OpenAPI specifications are imported into WireMock mappings.

Values:

• MATCHING_RESPONSE_CODE - Uses response status in request matchers convention
• SKELETON - Templates the mapping with the request and response structure
• SELECT_RESPONSE_STATUS - Uses generic matcher, relies on x-traffic-parrot-select-response-status header

Whether OpenAPI specifications should be automatically imported during startup.

Use Case: Useful for automated environments to pre-load API specifications.

Dependencies: Requires OpenAPI files in the configured openapi directory.

Controls OpenAPI request validation behavior.

Values:

• OFF - Turns off validation completely
• DEFAULT_VALIDATION - Turns on validation and provides default responses when not annotated
• ONLY_ANNOTATED - Turns on validation only for annotated specifications

Controls how skeleton mappings are generated from OpenAPI specifications.

Values: Same as trafficparrot.openapi.import.mode

Use Case: Specifically for generating template/skeleton responses rather than full imports.

Whether to validate HTTP mappings against OpenAPI specifications during startup.

Use Case: Set to true to prevent startup if any HTTP mapping references a URL path or method not defined in the loaded OpenAPI specification files.

Dependencies: Requires OpenAPI files in scenarios/{scenario}/openapi/. See the OpenAPI schema check documentation for details.

Defines the prefix for vendor-specific OpenAPI extensions used by Traffic Parrot.

Examples:

• x-traffic-parrot-validation - Custom validation rules
• x-traffic-parrot-select-response-status - Response selection headers

Critical: Required for validation system and custom extensions to work properly.

Answers and records IBM MQ CICS DPL bridge requests (messages with the format MQCICS) as the bridge does, decoding and encoding the COMMAREA with the copybooks in the scenario's copybooks directory. With it off, such a request is not answered and the log names this property.

Performance Profile: false

Use Case: Set to true to stand in for the CICS bridge. See CICS over IBM MQ.

Controls whether IBM MQ message bodies are logged.

Performance Profile: false

Use Case: Enable for debugging message content, disable for performance.

Controls whether message bodies are logged as printable characters only.

Use Case: When enabled, filters binary content to only printable characters for log readability.

Enables performance monitoring for IBM MQ operations.

Output: Logs "Total processing time" metrics for IBM MQ message processing.

Use Case: Enable for performance analysis and troubleshooting.

Controls whether headers are included in request message body during matching.

Impact: When true, excludes RFH headers from message body content when matching requests to recorded mappings.

Use Case: Improves matching accuracy by ignoring volatile header content.

Path to script file for IBM MQ queue replay on startup.

Format: File path or classpath URL to script file

Example: classpath:start-ibmmq-queue-replay-on-startup.txt

Use Case: Automate IBM MQ queue replay operations when Traffic Parrot starts.

Enables automatic JMS queue replay on startup.

Dependencies: Requires valid connection IDs for consumer and producer.

Use Case: Automate JMS message replay without manual intervention.

Specifies connection ID for consuming JMS requests on startup.

Format: Valid connection ID from jms-connections.json

Performance Profile: not-used

Dependencies: Requires trafficparrot.jms.start.queue.replay.on.startup=true

Specifies connection ID for sending JMS responses on startup.

Format: Valid connection ID from jms-connections.json

Performance Profile: not-used

Dependencies: Requires trafficparrot.jms.start.queue.replay.on.startup=true

Enables performance monitoring for JMS operations.

Output: Logs "Total processing time" metrics for JMS message processing.

Use Case: Enable for performance analysis and troubleshooting.

JMS delivery mode used when the simulator sends response or replayed messages.

Allowed Values: PERSISTENT, NON_PERSISTENT, or a numeric javax.jms.DeliveryMode / jakarta.jms.DeliveryMode constant (2 = persistent, 1 = non-persistent).

Use Case: Set to NON_PERSISTENT for higher throughput when message durability is not required.

Enables near-miss diagnostics for unmatched JMS, IBM MQ, and File messaging requests, similar to the HTTP near-miss diagnosis feature. When enabled, unmatched incoming messages and their closest mappings are recorded so they can be inspected in the messaging request log.

Use Case: Turn on while diagnosing mapping mismatches during stub development; leave off in performance-sensitive environments.

Whether to check JMS, native IBM® MQ and file message mappings against their mapping schemas during startup.

Use Case: Set to true to prevent startup if any messaging mapping in the current scenario does not match its schema, as the OpenAPI and gRPC startup checks do for HTTP and gRPC mappings. Files listed under exclude.files in messaging-schema.properties are skipped. trafficparrot validate runs the same check without starting the server, whatever this property says.

Memory limit (MB) for the embedded ActiveMQ internal broker used by the JMS simulator.

Use Case: Increase when stubbing high-throughput JMS scenarios that buffer many in-flight messages.

Temporary storage limit (MB) for the embedded ActiveMQ internal broker, used when memory-resident messages spill to temporary disk storage.

Persistent message store limit (MB) for the embedded ActiveMQ internal broker.

Scheduler store limit (MB) for the embedded ActiveMQ internal broker, used for delayed and scheduled message delivery.

Comma-separated patterns of file names that a connection never picks up from a request directory, because a client is still uploading them: on SFTP and FTP connections, and in the directories of a Local File System connection, which clients upload to through the embedded SFTP server. * matches any run of characters and ? one character; matching is case-sensitive. A value replaces the default list, and an empty value skips no names. Traffic Parrot's own in-progress uploads are always skipped.

Use Case: A client that uploads under .inprogress names: set *.inprogress. See How files on SFTP and FTP servers are picked up.

Whether Traffic Parrot runs the embedded SFTP server, the SFTP server a system under test uploads request files to and downloads replies from. Needs a licence that includes file messaging; without one, Traffic Parrot starts without the server and logs a warning. While off, none of the properties below is read, no port is bound and no file or directory is created.

Use Case: Virtualise a file gateway without an SFTP server of your own.

The port the embedded SFTP server listens on. A port already in use stops Traffic Parrot starting.

Use Case: A client that can only connect on port 22: set 22, and run Traffic Parrot with the privilege that port needs.

The address the embedded SFTP server listens on. The default accepts connections on every interface.

Use Case: Serve clients on the same machine only: set 127.0.0.1.

The directory the users' home directories are created under. A relative path resolves against the Traffic Parrot installation directory. A Local File System connection with the same rootDirectory lets one replay session serve every user. Uploads in progress are kept in .sftp-uploads under it.

The JSON file naming the users, their passwords or authorized keys and their home directories, read at start; see Traffic Parrot as the SFTP server. The configuration editor and Handlebars partials refuse the file under whatever name this property gives it, whether or not the server is enabled. An upgrade carries the default name only, so copy a renamed file by hand.

The server's private host key. Generated at the first start when the file does not exist, and never rewritten; to use your own, put an unencrypted RSA, ECDSA or Ed25519 key in OpenSSH or PEM format there before the first start. The configuration editor and Handlebars partials refuse the key under whatever name this property gives it. An upgrade carries the default name only, so copy a renamed key by hand.