Configuration Reference

Specifies the HTTP port number for the Traffic Parrot web user interface.

Usage: When HTTP is enabled, the GUI will be accessible at http://localhost:[port]

Example: Setting this to 8080 makes the GUI available at http://localhost:8080

Valid Range: 1-65535

Controls whether the HTTP connector for the GUI is enabled or disabled.

Values:

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

Security Note: You may want to set this to false and only use HTTPS for secure environments.

Specifies the HTTPS port number for the Traffic Parrot web user interface.

Usage: When HTTPS is enabled, the GUI will be accessible at https://localhost:[port]

Example: Setting this to 8079 makes the GUI available at https://localhost:8079

Valid Range: 1-65535

Related Properties:

• trafficparrot.gui.https.jks.resource - Path to the Java KeyStore file
• trafficparrot.gui.https.jks.password - Password for the KeyStore

Master switch that controls whether the system simulator component starts up.

Impact: When set to false, disables the entire simulation and mocking functionality (virtual services).

Main HTTP port for the simulator (virtual service/mock) that handles mock HTTP requests.

Note: This is separate from the GUI port (8080).

HTTPS port for the simulator (virtual service/mock) that handles mock HTTPS requests.

Note: Requires SSL/TLS configuration via keystore properties.

Base URL of a backend service for automatic passthrough proxying. When set, Traffic Parrot creates a catch-all proxy mapping on startup that forwards unmatched requests to this URL.

Use Case: Set to http://my-backend:8080 to forward unmatched requests to a real backend while selectively stubbing specific endpoints. See HTTP Passthrough Proxy.

Controls whether the automatic passthrough proxy mapping is created on startup.

Use Case: Set to false to temporarily disable passthrough proxying without removing the defaultTargetUrl configuration. See Disabling passthrough.

HTTP management API port for administrative operations on the simulator (virtual service/mock).

Use Case: Used by automation tools and the GUI for managing mappings and configurations.

JMS management port for administrative operations on JMS simulator (virtual service/mock).

Use Case: Used for managing JMS queue and topic virtualization.

Number of acceptor threads for the Jetty server handling simulator (virtual service/mock) requests.

Performance: Performance profile uses 4. Higher values improve connection handling under load.

Queue size for incoming connections. 0 means use system default.

Tuning: Increase for high-load scenarios to queue more incoming connections.

Maximum size in bytes for HTTP request headers.

Use Case: Increase if you need to handle requests with very large headers (e.g., large JWT tokens).

Maximum size in bytes for HTTP response headers.

Use Case: Increase if your mock responses include very large headers.

Number of container threads for processing requests.

Performance: Performance profile uses 500. Higher values allow more concurrent request processing.

Maximum time in milliseconds to wait for the simulator (virtual service/mock) to start up.

Default: 30000 (30 seconds)

Controls whether HTTP request logging is disabled in the system simulator.

Performance: Set to true to disable request logging for better performance.

Controls whether access logs are enabled for the system simulator.

Performance: Set to false to disable access logging to improve performance.

Maximum number of request journal entries kept in memory for verification. This bound applies to all request journals (HTTP, gRPC and JMS/IBM MQ), so each retains the last 1000 entries by default; older entries age out as new requests arrive. Raise this value if you need a longer request-log history (at the cost of more memory).

Performance: Performance profile uses 0 to disable. Higher values consume more memory but allow more request history.

Comma-separated list of HTTP response Content-Type values whose bodies are excluded from the request journal. The request headers and metadata are still journaled; only the response body is dropped.

Use Case: Prevents large binary responses (e.g. HLS .ts video segments, generic binary downloads) from filling the in-memory journal.

Enable HTTP performance monitoring for the simulator (virtual service/mock).

Use Case: Enable for detailed performance analysis of simulator (virtual service/mock) responses.

Root directory URL for traffic files (mappings, recorded data, etc.).

Examples: file:. (current dir), file:/path/to/data, classpath:data

Location of the JMS connections configuration file.

Use Case: Defines JMS broker connections for message virtualization.

Location of the IBM MQ connections configuration file.

Use Case: Defines IBM MQ manager connections for native MQ virtualization.

Location of the root directories configuration file.

Use Case: Defines additional root directories for organizing traffic data.

Path to the Java KeyStore file containing both keystore and truststore for simulator (virtual service/mock) SSL/TLS.

Use Case: Used for HTTPS simulator (virtual service/mock) and client certificate authentication.

Password for the simulator (virtual service/mock) keystore/truststore file.

Security: Change this in test and development environments.

Directory used to buffer multipart form-data uploads received by the HTTP simulator.

The special value JAVA_TEMP_DIR (or an empty value) resolves to the JVM's java.io.tmpdir system property at startup. Set to any absolute path to override.

Use Case: Point at a larger or faster filesystem when stubbing endpoints that accept large multipart uploads.

Maximum size, in megabytes, of a file uploaded through the admin UI's multipart upload forms: the Upload button on the Static Files browser (the HTTP __files manager), the Import skeleton… button on the HTTP and gRPC Add/Edit mapping pages (an OpenAPI/Swagger file imported as an HTTP skeleton, or a .proto file, .zip archive, or precompiled descriptor set imported as a gRPC message skeleton), and the HTTP Import mappings REST endpoint (/http/management/importMappings). The default is 10 MB.

An upload larger than this limit is rejected with HTTP 413 and an error message naming the limit (for example The uploaded file exceeds the maximum upload size of N MB), shown in the corresponding form's error area; the file is not stored or imported. Uploads at or under the limit are processed as before.

This limit applies only to file uploads through the admin UI and its REST API. It does not affect recorded traffic or mapping sizes.

Use Case: Raise the value when you need to upload larger response-body fixtures to the __files directory or import large OpenAPI specifications or proto descriptor sets through the UI; lower it to tighten the upload size accepted by the admin endpoints.

Master switch that controls whether gRPC system simulation functionality is enabled.

Enterprise Feature: Requires enterprise license with gRPC feature enabled.

Impact: When disabled, all gRPC functionality is unavailable.

Port number for gRPC TLS/HTTPS connections.

Valid Range: 1-65535

Security: Used for secure gRPC communications with TLS encryption.

Port number for gRPC non-TLS/HTTP connections.

Valid Range: 1-65535

Use Case: For development environments or when TLS is terminated elsewhere.

Controls whether the TLS gRPC server is started.

Use Case: Set to false to disable the TLS gRPC port, for example in development environments where encryption is not needed. At least one of TLS or non-TLS must remain enabled.

Controls whether the non-TLS gRPC server is started.

Use Case: Set to false to disable the non-TLS gRPC port, for example in production environments where only TLS connections should be accepted. At least one of TLS or non-TLS must remain enabled.

Controls whether mutual TLS client authentication is required.

Security: When enabled, clients must present valid certificates for authentication.

Path to server's trusted CA certificates for TLS.

Format: PEM format certificate file

Usage: Validates client certificates when mutual TLS is enabled.

Path to server's certificate file for TLS.

Format: PEM format certificate file

Usage: Server's public certificate for TLS connections.

Path to server's private key file for TLS.

Format: PEM format private key file

Security: Keep this file secure and private.

Path to client's trusted CA certificates for TLS.

Usage: For validating server certificates when making outbound gRPC calls.

Path to client's certificate file for TLS.

Usage: Client certificate for mutual TLS authentication.

Path to client's private key file for TLS.

Usage: Client private key for mutual TLS authentication.

Authority hostname override for client connections.

Use Case: Useful for testing with self-signed certificates or when hostname doesn't match certificate.

Controls whether outbound gRPC client connections always use TLS, regardless of the target URL scheme.

Use Case: Set to true to force TLS for environments where plain-text gRPC must never be used.

Number of Netty boss threads for gRPC server.

Values: DOUBLE_NUMBER_OF_PROCESSORS, NUMBER_OF_PROCESSORS, or specific integer

Performance: Boss threads handle connection acceptance.

Number of Netty worker threads for gRPC server.

Values: DOUBLE_NUMBER_OF_PROCESSORS, NUMBER_OF_PROCESSORS, or specific integer

Performance: Worker threads handle I/O operations.

Number of threads for receiving gRPC messages.

Performance: Dedicated threads for message reception processing.

Number of threads for sending gRPC messages.

Performance: Dedicated threads for message transmission processing.

Maximum number of messages that can wait in the send queue.

Performance: Higher values allow more message buffering but use more memory.

Duration in milliseconds for caching protobuf definitions.

Performance Profile: 1200000 (20 minutes)

Performance: Caching reduces file I/O for proto definitions.

Whether to populate the proto cache during startup.

Performance Profile: true

Trade-off: Slower startup for faster runtime performance.

Whether to warm up gRPC server components during startup.

Performance: Pre-initializes components for better first-request performance.

Comma-separated list of headers to exclude from request matching.

Use Case: Excludes volatile headers that shouldn't affect stubbing behavior.

Controls how protobuf field names are rendered in JSON.

Values:

• ORIGINAL - Preserve proto field names (e.g., input_name)
• CAMEL_CASE - Convert to camelCase (e.g., inputName)

Location of the openapi2proto plugin binary.

Values:

• AUTO_DETECT - Searches plugins directory, $PATH, and $HOME/go/bin
• Specific path - e.g., C:\example\openapi2proto.exe

Whether to validate gRPC mappings against proto schemas during startup.

Use Case: Set to true to prevent startup with invalid mappings.

Example: Prevents startup if mapping references non-existent proto method.

Whether to allow mappings with missing fields during schema validation.

Dependencies: Works with check.mapping.schema.on.startup

Flexibility: When true, allows partial field coverage in mappings.

Template for generating gRPC mapping file names.

Available properties: mapping.id, mapping.package, mapping.service, mapping.method, mapping.isSuccess, mapping.status.name, mapping.status.code

Available commands: countGrpcMappings with parameters for package, service, method, success, offset, format

Template for suffix when mapping file names collide.

Use Case: Appended when generated file name already exists.

Available properties: Same as main template plus additional Handlebars helpers.

Controls whether Handlebars template processing is enabled for HTTP responses.

Performance Profile: false

Dependencies: Works with trafficparrot.http.handlebars.helpers

Comma-separated list of Handlebars helper class names for HTTP.

Available Helpers:

• CsvDataFile - Reads data from CSV files using coordinates
• HttpNow - Provides current date/time functionality
• RandomDouble - Generates random double values
• RandomInteger - Generates random integer values
• RandomString - Generates random strings (up to 10,000 characters)
• RandomUUID - Generates random UUIDs
• Image - Renders a placeholder PNG image of a given size and returns it as a Base64-encoded string, not as image bytes. Pair it with the base64-decode-body response transformer so the response carries the raw PNG; see the {{image}} helper
• Evaluate - Executes script expressions
• ExecuteProcess - Runs an external process on the host and inserts its output. Remove it from this list to disable the helper

Controls whether the Cleanup entry appears in the HTTP navigation dropdown, linking to the HTTP Mock Cleanup page that consolidates and prunes recorded mappings.

Performance Profile: false

Use Case: Show or hide the Cleanup link in the HTTP menu. Set to false to hide the navigation link; the cleanup page and its REST API remain reachable by direct URL regardless of this setting; the property controls only the visibility of the navigation link.

Enables the external-process HTTP response transformer, which passes the response through a user-supplied executable (the "middleware") over a JSON envelope on stdin/stdout.

Performance Profile: false

Use Case: Run language-agnostic middleware to mutate HTTP responses, off by default. While false, a mapping referencing the transformer is inert and logs a warning.

Security: the executable runs as the Traffic Parrot OS user with no sandbox. Requires trafficparrot.http.externalprocess.allowedDir to be set. Enable only on trusted hosts; see the threat model.

A single directory that the external-process transformer is restricted to. Only executables whose canonical (symlink-resolved) path is under this directory may be invoked.

Performance Profile: (empty)

Use Case: Confine external-process middleware to a dedicated, operator-vetted directory of scripts.

Note: an empty value means nothing is allowed, even when trafficparrot.http.externalprocess.enabled=true; both must be set for the feature to run.

Master switch for importing a specification from a URL (introduced for the import-from-URL feature; off by default). When enabled, Traffic Parrot may make a server-side HTTP/HTTPS request from the Traffic Parrot host to fetch a specification to import. The same switch gates the fetch of an OpenAPI example that points at a URL with externalValue, whether the specification is imported from the web UI, read from the OpenAPI directory at startup or built by the MCP generate_mappings_from_openapi tool: while false, that example is replaced with a Traffic Parrot could not fetch externalValue: <url> (<reason>) placeholder and the mapping is still created. Enabling the switch to keep fetching externalValue examples also enables the Import from URL control in the web UI and its server-side fetch for the same allow-listed hosts; the two share one switch by design.

Performance Profile: false

Use Case: Allow operators to opt in to fetching specifications over the network. While false, no URL can be imported.

Security: because the request originates from the Traffic Parrot host, this is gated by an explicit allow-list. Requires trafficparrot.http.importfromurl.allowedHosts to be set. Enable only on trusted hosts.

Comma-separated allow-list of host or host:port entries that the import-from-URL feature may fetch from. This is the SSRF allow-list: only hosts an operator explicitly lists may be reached. The same list confines the fetch of an OpenAPI example that points at a URL with externalValue during an OpenAPI import, so an example hosted anywhere else is replaced with a placeholder naming the host that was refused.

Performance Profile: (empty)

Use Case: Confine import-from-URL fetches to a vetted set of hosts.

Note: fail-closed: an empty value means nothing is importable, even when trafficparrot.http.importfromurl.enabled=true; both must be set for the feature to run. A resolved destination is still rejected if it is a loopback, link-local, private, or cloud-metadata address, even when its host is allow-listed.

Enables JWT (JSON Web Token) processing capabilities for HTTP.

Performance Profile: false

Use Case: For JWT token validation and processing in HTTP requests.

Enables HTTP response modification capabilities.

Performance Profile: false

Use Case: Allows dynamic modification of HTTP responses before sending to clients.

Enables automatic HTTP OPTIONS response handling.

Performance Profile: false

Use Case: Automatically handles CORS preflight requests.

Enables SOAP message signing capabilities.

Performance Profile: false

Use Case: For WS-Security SOAP message signing functionality.

Enables webhook functionality for HTTP responses.

Performance Profile: false

Use Case: Allows HTTP responses to trigger outbound webhook calls.

Comma-separated list of response transformer class names for HTTP simulator (mock)s.

Performance Profile: (empty)

Default Transformers:

• UpdateContentLengthTransformer - Automatically updates Content-Length headers to match response body size
• HlsStreamTransformer - Serves HLS video streaming content (.m3u8 playlists and .ts segments). See built-in response transformers for details.

Use Case: Custom transformation of HTTP responses before sending to clients. Transformers can modify response content, headers, status codes, and implement cross-cutting concerns like logging, monitoring, or security.

Examples:

• Single: com.example.MyTransformer
• Multiple: com.example.TransformerA,com.example.TransformerB
• Disabled: (empty)

Comma-separated list of response transformer class names for JMS.

Performance Profile: (empty)

Default Transformer: JmsPassthroughMessage - Passes JMS messages through without modification

Comma-separated list of response transformer class names for IBM MQ.

Use Case: Custom transformation of IBM MQ messages before sending responses.

Comma-separated list of response transformer class names for file-based messaging.

Use Case: Custom transformation of file messages before processing.

Controls Handlebars template processing for JMS messages.

Performance Profile: false

JMS-specific Handlebars helpers (excludes CSV and HTTP-specific helpers).

Performance Profile: (empty)

Controls Handlebars template processing for IBM MQ messages.

Performance Profile: false

IBM MQ-specific Handlebars helpers (same as JMS).

Performance Profile: (empty)

Controls Handlebars template processing for file-based messaging.

Performance Profile: false

File messaging-specific Handlebars helpers.

Performance Profile: (empty)

Master switch to enable/disable Okta SSO functionality.

Impact: When enabled, adds OAuth2/OIDC authentication to the web UI.

Flow: Implements Authorization Code flow with session-based and Bearer token authentication.

OAuth2 client identifier for the Traffic Parrot application registered in Okta.

Usage: Used in authorization URL construction and token exchange requests.

Required: Application will fail if not properly configured.

OAuth2 client secret for authenticating with Okta token endpoint.

Security: Combined with clientId for Basic Auth in token exchange.

Storage: Sensitive credential that should be securely stored.

Okta authorization endpoint for OAuth2 Authorization Code flow.

Parameters: Includes client_id, response_type=code, scope=openid, redirect_uri, state

Format: Must be valid HTTPS URL pointing to Okta authorization server.

Okta token endpoint for exchanging authorization codes for access tokens.

Usage: HTTP POST request with grant_type=authorization_code, redirect_uri, code

Response: Extracts access_token for JWT validation.

Okta issuer URI for JWT token validation.

JWT Validation: Validates JWT 'iss' claim matches this value.

Security: Part of JWT signature verification process.

Expected audience claim in JWT access tokens.

JWT Validation: Validates JWT 'aud' claim contains this value.

Security: Ensures tokens are intended for this application.

OAuth2 redirect URI where Okta returns authorization codes.

Configuration: Must match exactly what's configured in Okta application settings.

Usage: URL-encoded in authorization requests and token exchange requests.

Specifies license server URL for on-premise license validation.

Values:

• DEFAULT - Use default cloud-based licensing
• host:port - HTTP license server
• https://host:port - HTTPS license server

Use Case: For on-premise licenses with local license servers.

Custom HTTP headers for license server communications.

Format: Comma-separated Key:Value pairs

Example: Authorization:Bearer token,Environment:Test

Use Case: Add authentication, routing, or other custom headers to license requests.

Enables JMX monitoring for the simulator simulator (virtual service/mock).

Use Case: Enable for remote monitoring and management using JMX tools.

MBeans: Exposes management beans for simulator simulator (virtual service/mock) monitoring.

Specifies the port for simulator (virtual service/mock) JMX connector.

Valid Range: 1-65535

Dependencies: Requires trafficparrot.virtualservice.jmx.enabled=true

Access: JMX management interface available on this port.