<!-- Generated from https://trafficparrot.com/documentation/5.65.x/properties.html by scripts/generate-md-mirrors.sh. Do not edit: edit the .html and regenerate. -->

# Configuration Reference

<a id="overview"></a>
## Overview

This page provides a reference for all configuration properties available in the `trafficparrot.properties` file. These properties control various aspects of Traffic Parrot's behavior, including GUI settings, system simulation configuration, and more.

**Important Terminology:** Traffic Parrot is a **system and API simulator** that creates simulations of your APIs and services. Throughout this documentation, you'll see references to:

- System and API simulation (simulators)
- Service virtualization (virtual services)
- API mocking (mocks)

All these terms refer to the same capability: creating simulated versions of real services, APIs, and systems that respond to requests as if they were the actual services.

To modify these properties, edit the `trafficparrot.properties` file in your Traffic Parrot installation directory and restart the application for changes to take effect.

<a id="gui-properties"></a>
## Web User Interface Properties

These properties configure the Traffic Parrot web user interface (GUI) settings.

### Web User Interface HTTP/HTTPS Port Configuration

| Property Name | Default Value | Description |
| --- | --- | --- |
| `trafficparrot.gui.http.port` | `8080` | Specifies the HTTP port number for the Traffic Parrot web user interface.<br><br>**Usage:** When HTTP is enabled, the GUI will be accessible at `http://localhost:[port]`<br><br>**Example:** Setting this to `8080` makes the GUI available at `http://localhost:8080`<br><br>**Valid Range:** 1-65535 |
| `trafficparrot.gui.http.port.enabled` | `true` | Controls whether the HTTP connector for the GUI is enabled or disabled.<br><br>**Values:**<br><br>- `true` - Creates an HTTP server connector on the specified HTTP port<br>- `false` - No HTTP connector is created; GUI is not accessible via HTTP<br><br>**Security Note:** You may want to set this to `false` and only use HTTPS for secure environments. |
| `trafficparrot.gui.https.port` | `8079` | Specifies the HTTPS port number for the Traffic Parrot web user interface.<br><br>**Usage:** When HTTPS is enabled, the GUI will be accessible at `https://localhost:[port]`<br><br>**Example:** Setting this to `8079` makes the GUI available at `https://localhost:8079`<br><br>**Valid Range:** 1-65535<br><br>**Related Properties:**<br><br>- `trafficparrot.gui.https.jks.resource` - Path to the Java KeyStore file<br>- `trafficparrot.gui.https.jks.password` - Password for the KeyStore |

### Web User Interface HTTPS Configuration

| Property Name | Default Value | Description |
| --- | --- | --- |
| `trafficparrot.gui.https.port.enabled` | `true` | Controls whether the HTTPS connector for the GUI is enabled.<br><br>**Values:**<br><br>- `true` - Creates an HTTPS server connector on the specified HTTPS port<br>- `false` - No HTTPS connector is created; GUI is not accessible via HTTPS |
| `trafficparrot.gui.https.jks.resource` | `certificates/user-interface-https.jks` | Specifies the path to the Java KeyStore (JKS) file containing the SSL/TLS certificate for HTTPS connections to the GUI.<br><br>**Note:** The path is relative to the Traffic Parrot installation directory or can be an absolute path. |
| `trafficparrot.gui.https.jks.password` | `trafficparrot` | The password for the JKS keystore file specified in `trafficparrot.gui.https.jks.resource`.<br><br>**Security Note:** In test and development environments, use a strong password and consider using environment variables or secure credential stores. |

> #### Important Notes
>
> - Both HTTP and HTTPS can be enabled simultaneously, allowing access via both protocols
> - These GUI ports are separate from the simulator (virtual service/mock) ports (8081 for HTTP, 8082 for HTTPS)
> - The GUI ports are used for managing Traffic Parrot, while simulator (virtual service/mock) ports handle the actual mocked/virtualized traffic
> - Ensure the selected ports are not already in use by other applications

### Web User Interface Security and Access Control

| Property Name | Default Value | Description |
| --- | --- | --- |
| `trafficparrot.gui.security.mode` | `ALLOW_ALL` | Controls the authentication mode for the GUI.<br><br>**Values:**<br><br>- `ALLOW_ALL` - No authentication required (default)<br>- `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](https://trafficparrot.com/documentation/5.65.x/user_guide.html#start-logs) or the HTTPS port: a plain-HTTP port sends the password unencrypted. Stubs and the admin API on those ports are not affected.<br><br>**Security Note:** For test and development environments, it's recommended to use `LOGIN_PROPERTIES` mode with HTTPS enabled. |
| `trafficparrot.gui.enabled` | `true` | Master switch to enable or disable the GUI entirely.<br><br>**Values:**<br><br>- `true` - GUI server starts normally<br>- `false` - GUI server won't start (useful for headless/API-only deployments) |

### Web User Interface Advanced Configuration

| Property Name | Default Value | Description |
| --- | --- | --- |
| `trafficparrot.gui.forwardToVirtualService.enabled` | `true` | When enabled, requests made to the GUI port that don't match GUI endpoints will be forwarded to the simulator (virtual service/mock) port.<br><br>**Use Case:** This allows the GUI and simulator (virtual service/mock) to effectively share the same port, simplifying configuration in some scenarios.<br><br>**Note:** In performance profile, this is disabled by default to maximize throughput. |
| `trafficparrot.gui.jmx.enabled` | `false` | Controls whether JMX (Java Management Extensions) is enabled for the GUI server.<br><br>**Use Case:** Enable this for remote monitoring and management of the GUI server using JMX tools. |
| `trafficparrot.gui.jmx.port` | `8085` | The port number for JMX connections when JMX is enabled.<br><br>**Valid Range:** 1-65535<br><br>**Note:** Only effective when `trafficparrot.gui.jmx.enabled` is set to `true`. |
| `trafficparrot.gui.startup.timeout.milliseconds` | `45000` | The maximum time in milliseconds to wait for the GUI server to start up before timing out.<br><br>**Default:** 45000 (45 seconds)<br><br>**Use Case:** Increase this value if the GUI server takes longer to start on slower systems or when loading large configurations. |
| `trafficparrot.gui.http.queuedThreadPool.maxThreads` | `200` | Maximum number of threads in the Jetty thread pool for handling GUI HTTP requests.<br><br>**Performance Note:** This affects the GUI server's ability to handle concurrent connections. Increase for high-concurrency scenarios.<br><br>**Resource Impact:** Each thread consumes memory, so balance this with available system resources. |
| `trafficparrot.gui.http.queuedThreadPool.minThreads` | `8` | Sets the minimum number of threads in the Jetty thread pool for the Traffic Parrot GUI HTTP server.<br><br>**Performance Impact:** Controls the base number of threads available for handling GUI requests. Higher values ensure better responsiveness under load. |
| `trafficparrot.gui.config.files.allowedFilesToEdit` | `.json$, .csv$, .properties$, .hbs$` | 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.<br><br>The shipped list allows `.json`, `.csv` and `.properties` files and `.hbs` files, so a Handlebars partial that a response template includes (see [Template files](https://trafficparrot.com/documentation/5.65.x/dynamic.html#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.<br><br>**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. |
| `trafficparrot.gui.config.files.notAllowedFilesToEdit` | `^\.,\.git,target, deleted-scenarios, trafficparrot.properties, trafficparrot.performance.properties, trafficparrot.gui.login.properties, .*-connections\.json, sftp-server-users\.json, log4j,lib` | 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.<br><br>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.<br><br>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](https://trafficparrot.com/documentation/5.65.x/filemessage.html#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.<br><br>**Security:** Blocks access to system-critical files and directories. |

<a id="mcp-properties"></a>
### MCP Endpoint for AI Assistants

These properties control who may reach the `/mcp` endpoint, which lets an AI assistant drive Traffic Parrot. The endpoint is served on the web user interface port. See the [MCP endpoint reference](https://trafficparrot.com/documentation/5.65.x/mcp.html) for the endpoint, the handshake and the tools it exposes, and [Connect your assistant with MCP](https://trafficparrot.com/documentation/5.65.x/generate-mocks-with-ai-agent.html#mcp) to point a client at it.

| Property Name | Default Value | Description |
| --- | --- | --- |
| `trafficparrot.mcp.authenticator` | `ALLOW_LOCAL_HOST_ONLY` | How requests to `/mcp` are authenticated.<br><br>`ALLOW_LOCAL_HOST_ONLY` (the default) accepts requests from this machine only, and needs no token.<br><br>`BEARER_TOKEN` accepts requests from anywhere, and every one must carry an `Authorization: Bearer <token>` header matching `trafficparrot.mcp.token`.<br><br>**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. |
| `trafficparrot.mcp.token` | `(none)` | The bearer token that a request to `/mcp` must carry.<br><br>Required when `trafficparrot.mcp.authenticator=BEARER_TOKEN`; Traffic Parrot will not start without it. Ignored otherwise.<br><br>**Security:** Choose your own secret. There is no default, deliberately: a shipped default token would be a published one. |
| `trafficparrot.mcp.allowedOrigins` | `(none)` | 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.<br><br>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](https://trafficparrot.com/documentation/5.65.x/mcp.html#access-origin).<br><br>**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. |

<a id="virtualservice-properties"></a>
## System Simulation and Mocking Properties

These properties configure the core system simulation functionality that handles HTTP/HTTPS traffic. These simulators are also referred to as virtual servcies or API mocks in various contexts.

### Basic Simulator and Mock Configuration

| Property Name | Default Value | Description |
| --- | --- | --- |
| `trafficparrot.virtualservice.start` | `true` | Master switch that controls whether the system simulator component starts up.<br><br>**Impact:** When set to `false`, disables the entire simulation and mocking functionality (virtual services). |
| `trafficparrot.virtualservice.http.port` | `8081` | Main HTTP port for the simulator (virtual service/mock) that handles mock HTTP requests.<br><br>**Note:** This is separate from the GUI port (8080). |
| `trafficparrot.virtualservice.https.port` | `8082` | HTTPS port for the simulator (virtual service/mock) that handles mock HTTPS requests.<br><br>**Note:** Requires SSL/TLS configuration via keystore properties. |
| `trafficparrot.virtualservice.https.tls.protocols` | `(empty)` | Comma-separated TLS protocol versions the virtual service HTTPS listener offers, in place of the Java defaults (TLSv1.3 and TLSv1.2). An entry is a version name or a regular expression matching the whole name; one that matches no version the JVM supports is reported as a warning at startup. The default exclusions (the SSL protocols) stay in force. Blank keeps the defaults.<br><br>**Use Case:** Set to `TLSv1.3` to refuse TLSv1.2 clients. See [Restrict the TLS protocol versions and cipher suites](https://trafficparrot.com/documentation/5.65.x/user_guide.html#https-certificates-tls). |
| `trafficparrot.virtualservice.https.tls.protocols.exclude` | `(empty)` | Comma-separated TLS protocol versions the virtual service HTTPS listener refuses, added to the default exclusions (the SSL protocols). An excluded version stays excluded even if `trafficparrot.virtualservice.https.tls.protocols` names it. |
| `trafficparrot.virtualservice.https.tls.cipherSuites` | `(empty)` | Comma-separated cipher suites the virtual service HTTPS listener offers, in place of the Java defaults. An entry is a suite name or a regular expression, for example `^TLS_AES_.*$`; one that matches no suite the JVM supports is reported as a warning at startup. The default exclusions (the RSA key exchange, SHA-1, MD5, NULL and anonymous suites) stay in force, so an entry naming one of those is dropped. Blank keeps the defaults. |
| `trafficparrot.virtualservice.https.tls.cipherSuites.exclude` | `(empty)` | Comma-separated cipher suites the virtual service HTTPS listener refuses, added to the default exclusions (the RSA key exchange, SHA-1, MD5, NULL and anonymous suites). An entry is a suite name or a regular expression, and an excluded suite stays excluded even if `trafficparrot.virtualservice.https.tls.cipherSuites` names it.<br><br>**Use Case:** Set to `TLS_AES_128_GCM_SHA256` to refuse that suite. The protocol versions and cipher suites in force are logged at startup. |
| `trafficparrot.virtualservice.proxy.defaultTargetUrl` | `(empty)` | 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.<br><br>**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](https://trafficparrot.com/documentation/5.65.x/http.html#passthrough-proxy). |
| `trafficparrot.virtualservice.proxy.enabled` | `true` | Controls whether the automatic passthrough proxy mapping is created on startup.<br><br>**Use Case:** Set to `false` to temporarily disable passthrough proxying without removing the `defaultTargetUrl` configuration. See [Disabling passthrough](https://trafficparrot.com/documentation/5.65.x/http.html#passthrough-proxy-disable). |
| `trafficparrot.virtualservice.http.management.port` | `8083` | HTTP management API port for administrative operations on the simulator (virtual service/mock).<br><br>**Use Case:** Used by automation tools and the GUI for managing mappings and configurations. |
| `trafficparrot.virtualservice.jms.management.port` | `9093` | JMS management port for administrative operations on JMS simulator (virtual service/mock).<br><br>**Use Case:** Used for managing JMS queue and topic virtualization. |

### Simulator and Mock Jetty Server Configuration

| Property Name | Default Value | Description |
| --- | --- | --- |
| `trafficparrot.virtualservice.jettyAcceptors` | `1` | Number of acceptor threads for the Jetty server handling simulator (virtual service/mock) requests.<br><br>**Performance:** Performance profile uses 4. Higher values improve connection handling under load. |
| `trafficparrot.virtualservice.jettyAcceptQueueSize` | `0` | Queue size for incoming connections. 0 means use system default.<br><br>**Tuning:** Increase for high-load scenarios to queue more incoming connections. |
| `trafficparrot.virtualservice.jettyHeaderRequestSize` | `8192` | Maximum size in bytes for HTTP request headers.<br><br>**Use Case:** Increase if you need to handle requests with very large headers (e.g., large JWT tokens). |
| `trafficparrot.virtualservice.jettyHeaderResponseSize` | `8192` | Maximum size in bytes for HTTP response headers.<br><br>**Use Case:** Increase if your mock responses include very large headers. |
| `trafficparrot.virtualservice.containerThreads` | `100` | Number of container threads for processing requests.<br><br>**Performance:** Performance profile uses 500. Higher values allow more concurrent request processing. |
| `trafficparrot.virtualservice.startup.timeout.milliseconds` | `30000` | Maximum time in milliseconds to wait for the simulator (virtual service/mock) to start up.<br><br>**Default:** 30000 (30 seconds) |

### Simulator and Mock Logging and Monitoring

| Property Name | Default Value | Description |
| --- | --- | --- |
| `trafficparrot.virtualservice.httpRequestLoggingDisabled` | `false` | Controls whether HTTP request logging is disabled in the system simulator.<br><br>**Performance:** Set to `true` to disable request logging for better performance. |
| `trafficparrot.virtualservice.accessLogsEnabled` | `true` | Controls whether access logs are enabled for the system simulator.<br><br>**Performance:** Set to `false` to disable access logging to improve performance. |
| `trafficparrot.virtualservice.maxRequestJournalEntries` | `1000` | 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).<br><br>**Performance:** Performance profile uses 0 to disable. Higher values consume more memory but allow more request history. |
| `trafficparrot.virtualservice.journal.excludeBodyContentTypes` | `video/MP2T,application/octet-stream` | 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.<br><br>**Use Case:** Prevents large binary responses (e.g. HLS `.ts` video segments, generic binary downloads) from filling the in-memory journal. |
| `trafficparrot.virtualservice.http.monitorPerformance` | `false` | Enable HTTP performance monitoring for the simulator (virtual service/mock).<br><br>**Use Case:** Enable for detailed performance analysis of simulator (virtual service/mock) responses. |

### Simulator and Mock File System and Resources

| Property Name | Default Value | Description |
| --- | --- | --- |
| `trafficparrot.virtualservice.trafficFilesRootUrl` | `file:.` | Root directory URL for traffic files (mappings, recorded data, etc.).<br><br>**Examples:** `file:.` (current dir), `file:/path/to/data`, `classpath:data` |
| `trafficparrot.virtualservice.jmsConnectionsUrl` | `classpath:jms-connections.json` | Location of the JMS connections configuration file.<br><br>**Use Case:** Defines JMS broker connections for message virtualization. |
| `trafficparrot.virtualservice.ibmMqConnectionsUrl` | `classpath:ibm-mq-connections.json` | Location of the IBM MQ connections configuration file.<br><br>**Use Case:** Defines IBM MQ manager connections for native MQ virtualization. |
| `trafficparrot.virtualservice.rootDirectoriesUrl` | `classpath:root-directories.json` | Location of the root directories configuration file.<br><br>**Use Case:** Defines additional root directories for organizing traffic data. |
| `trafficparrot.virtualservice.keystoreAndTruststore.jks.resource` | `certificates/trafficparrot-keystore-and-truststore.jks` | Path to the Java KeyStore file containing both keystore and truststore for simulator (virtual service/mock) SSL/TLS.<br><br>**Use Case:** Used for HTTPS simulator (virtual service/mock) and client certificate authentication. |
| `trafficparrot.virtualservice.keystoreAndTruststore.jks.password` | `trafficparrot` | Password for the simulator (virtual service/mock) keystore/truststore file.<br><br>**Security:** Change this in test and development environments. |
| `trafficparrot.multipart.location` | `JAVA_TEMP_DIR` | Directory used to buffer multipart form-data uploads received by the HTTP simulator.<br><br>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.<br><br>**Use Case:** Point at a larger or faster filesystem when stubbing endpoints that accept large multipart uploads. |
| `trafficparrot.multipart.upload.max.size.mb` | `10` | 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](https://trafficparrot.com/documentation/5.65.x/http.html#http-skeletons), or a `.proto` file, `.zip` archive, or precompiled descriptor set imported as a [gRPC message skeleton](https://trafficparrot.com/documentation/5.65.x/grpc.html#edit-grpc-skeletons)), and the HTTP [Import mappings](https://trafficparrot.com/documentation/5.65.x/http.html#import-http-rest-api) REST endpoint (`/http/management/importMappings`). The default is `10` MB.<br><br>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.<br><br>The same limit caps the form a JMS, IBM® MQ or file message **Add/Edit mapping** Save sends, response body included; see [Binary replies in the editor](https://trafficparrot.com/documentation/5.65.x/filemessage.html#binary-files-editor).<br><br>This limit applies to file uploads through the admin UI and its REST API and to the form those three **Add/Edit mapping** pages send on Save. It does not affect recorded traffic or the size of a mapping file on disk.<br><br>**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. |

<a id="recording-properties"></a>
## Simulator and Mock Recording Properties

These properties control how Traffic Parrot records and processes traffic from real services.

| Property Name | Default Value | Description |
| --- | --- | --- |
| `trafficparrot.virtualservice.ungzipBeforeWritingToDisk` | `true` | Controls whether gzipped responses are uncompressed before saving to disk during recording.<br><br>**Impact:** When enabled, makes recorded traffic files more readable but may increase disk usage. |
| `trafficparrot.virtualservice.enableRedirectHandling` | `false` | Enables automatic following of HTTP redirects during recording.<br><br>**Use Case:** When enabled, Traffic Parrot will follow redirect chains automatically during proxy recording.<br><br>See [Handling HTTP redirects during recording](https://trafficparrot.com/documentation/5.65.x/http.html#recording-redirect-handling) for the full behaviour and a comparison of the enabled and disabled modes. |
| `trafficparrot.virtualservice.recordOnlyContentTypesContaining` | `TP_RECORD_ALL_ CONTENT_TYPES` | Filters recording to only capture specific content types.<br><br>**Default:** `TP_RECORD_ALL_CONTENT_TYPES` (special value meaning record all)<br><br>**Example:** `application/javascript,application/xml` to record only JS and XML content |
| `trafficparrot.http.recording.response.rewrite.regex` | ` ` | Regex patterns applied to response bodies **during recording**, rewriting the content as the client sees it before it is matched and saved.<br><br>**Format:** `pattern->replacement,pattern2->replacement2`<br><br>**Example:** `https://api\.example\.com->http://localhost:8081` rewrites a production host to your local simulator host.<br><br>**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.<br><br>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. |
| `trafficparrot.http.recording.storage.rewrite.regex` | ` ` | 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.<br><br>This property applies to the **response body only**. To rewrite recorded request bodies, use `trafficparrot.http.recording.request.storage.rewrite.regex` below.<br><br>**Format:** `pattern->replacement,pattern2->replacement2`<br><br>**Example:** `http://localhost:8081->http://{{request.requestLine.host}}` stores a templated host so the saved mapping replays against whatever host the request arrives on.<br><br>**Use Case:** Keep recorded files environment-agnostic by templating host-specific values as they are written to disk.<br><br>A malformed rule stops Traffic Parrot from starting, naming the rule at fault, as for `trafficparrot.http.recording.response.rewrite.regex`. |
| `trafficparrot.http.recording.request.storage.rewrite.regex` | ` ` | Regex patterns applied **when saving request bodies to disk** during recording. Empty by default, so nothing is rewritten unless you configure it.<br><br>**Format:** `pattern->replacement,pattern2->replacement2`<br><br>**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`.<br><br>**Use Case:** Keep credentials, tokens and personal data out of recorded traffic files.<br><br>**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](https://trafficparrot.com/documentation/5.65.x/http.html#recording-request-body-rewriting) for the two ways to handle that, and for which content types are covered.<br><br>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. |
| `trafficparrot.http.recording.redaction.enabled` | `false` | 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.<br><br>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.<br><br>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](https://trafficparrot.com/documentation/5.65.x/http.html#recording-header-redaction) for what is and is not covered.<br><br>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.<br><br>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. |
| `trafficparrot.http.recording.redaction.strategy` | `PLACEHOLDER` | 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.<br><br>**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. |
| `trafficparrot.http.recording.redaction.placeholder` | `***REDACTED***` | 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. |
| `trafficparrot.http.recording.redaction.headers` | ` ` | 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.<br><br>**Example:** `X-Api-Key, X-Session-Token` |
| `trafficparrot.http.recording.response.inlineJson` | `false` | Sets the default state of the **Keep valid-JSON response body inline** checkbox in the Advanced parameters section of the HTTP Record page.<br><br>**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.<br><br>This property only seeds the checkbox's initial state; the checkbox on the Record page overrides it for that session.<br><br>See [Keeping JSON response bodies inline](https://trafficparrot.com/documentation/5.65.x/http.html#recording-inline-json) for the full behaviour. |
| `trafficparrot.http.recording.request.externaliseToFile` | `false` | Sets the default state of the **Externalise request body to file** checkbox in the Advanced parameters section of the HTTP Record page.<br><br>**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.<br><br>This property only seeds the checkbox's initial state; the checkbox on the Record page overrides it for that session.<br><br>See [Externalising request bodies to files](https://trafficparrot.com/documentation/5.65.x/http.html#recording-externalise-request) for the full behaviour. |
| `trafficparrot.virtualservice.gzipHttpResponseEnabled` | `true` | Enables/disables gzip compression of HTTP responses from the simulator (virtual service/mock).<br><br>**Performance:** Reduces bandwidth usage but increases CPU usage for compression. |

<a id="caching-properties"></a>
## Simulator and Mock Caching and Performance Properties

These properties control caching behavior and performance optimizations.

| Property Name | Default Value | Description |
| --- | --- | --- |
| `trafficparrot.virtualservice.mapping.cache.milliseconds` | `0` | Cache duration for stub mappings in milliseconds.<br><br>**Performance:** Performance profile uses 10,000,000 ms. Caching reduces file I/O but uses more memory.<br><br>**Default:** 0 (no caching) |
| `trafficparrot.virtualservice.handlebars.maxCacheEntries` | `0` | Maximum number of entries in the Handlebars template cache.<br><br>**Performance:** Performance profile uses 10,000. Caching improves template rendering speed but uses memory.<br><br>**Default:** 0 (no caching) |
| `trafficparrot.virtualservice.handlebars.select.indexAndCacheCsvFiles` | `false` | Enables indexing and caching of CSV files used in Handlebars select helpers.<br><br>**Performance:** Performance profile enables this. Significantly improves performance when using CSV data in templates. |

<a id="handlebars-properties"></a>
## Simulator and Mock Handlebars Template Properties

These properties control Handlebars templating behavior across all simulator (virtual service/mock) types.

| Property Name | Default Value | Description |
| --- | --- | --- |
| `trafficparrot.virtualservice.handlebars.normalizeHelperParameters` | `false` | Controls parameter normalization in Handlebars helpers.<br><br>**Impact:** Affects how helper parameters are processed and validated. |
| `trafficparrot.virtualservice.handlebars.now.provider` | `HANDLEBARS` | Selects the implementation for the `{{now}}` helper.<br><br>**Values:**<br><br>- `WIREMOCK` - Uses WireMock version of {{now}} helper<br>- `HANDLEBARS` - Uses Handlebars.java version of {{now}} helper |
| `trafficparrot.virtualservice.handlebars.now.dynamic` | `false` | Allows runtime specification of the `{{now}}` provider.<br><br>**Usage:** When `true`, allows `{{now provider='WIREMOCK'}}` syntax in templates. |
| `trafficparrot.virtualservice.handlebars.throwErrors` | `false` | Controls whether Handlebars helper errors cause request failures or embed inline error strings in responses.<br><br>**Values:**<br><br>- `false` (default) - Errors are embedded as `{{ helperName ERROR: message }}` in the response body<br>- `true` - Errors throw exceptions, resulting in HTTP 500 or messaging failures<br><br>**Use Case:** Enable in CI/CD pipelines and contract testing to make template errors visible as test failures. See [Error handling](https://trafficparrot.com/documentation/5.65.x/dynamic.html#error-handling). |

<a id="advanced-properties"></a>
## Advanced Properties

These properties control advanced Traffic Parrot behavior and system-level configurations.

| Property Name | Default Value | Description |
| --- | --- | --- |
| `trafficparrot.virtualservice.http.no.mapping.found.code` | `900` | HTTP status code returned when no mapping is found for a request.<br><br>**Use Case:** Custom error code to distinguish between unmapped requests and real HTTP errors. |
| `trafficparrot.mostly.printable.characters.threshold` | `0.95` | Threshold (0.0-1.0) for determining if content is mostly printable characters.<br><br>**Default:** 0.95 (95% of characters must be printable)<br><br>**Use Case:** Used for message body analysis and logging decisions. |
| `trafficparrot.jms.skipRecordingProperties` | `JMSXDeliveryCount, JMSXUserID, JMS_IBM_PutApplType, JMS_IBM_PutDate, JMS_IBM_PutTime, JMSXAppID, JMS_IBM_MsgToken` | Comma-separated list of JMS properties to skip during recording.<br><br>**Use Case:** Excludes system-generated or time-sensitive properties from recorded JMS messages.<br><br>**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. |
| `trafficparrot.ibmmq.connect.options.accessQueue.input` | `MQOO_INPUT_SHARED\|MQOO_FAIL_IF_QUIESCING` | IBM MQ connection options for queue access operations.<br><br>**IBM MQ Flags:** Controls how queues are opened for input (consumer) operations. Use `MQOO_INPUT_EXCLUSIVE` for exclusive access to a queue. |
| `trafficparrot.ibmmq.connect.options.accessQueue.output` | `MQOO_OUTPUT\|MQOO_FAIL_IF_QUIESCING` | IBM MQ connection options for queue access operations.<br><br>**IBM MQ Flags:** Controls how queues are opened for output (producer) operations. |

<a id="grpc-properties"></a>
## gRPC System Simulation Properties

These properties configure the gRPC system simulation functionality for protocol buffer-based services. This includes creating gRPC simulators (also known as virtual services or API mocks).

### Basic gRPC Configuration

| Property Name | Default Value | Description |
| --- | --- | --- |
| `trafficparrot.virtualservice.grpc.enabled` | `true` | Master switch that controls whether gRPC system simulation functionality is enabled.<br><br>**Enterprise Feature:** Requires enterprise license with gRPC feature enabled.<br><br>**Impact:** When disabled, all gRPC functionality is unavailable. |
| `trafficparrot.virtualservice.grpc.tls.port` | `5551` | Port number for gRPC TLS/HTTPS connections.<br><br>**Valid Range:** 1-65535<br><br>**Security:** Used for secure gRPC communications with TLS encryption. |
| `trafficparrot.virtualservice.grpc.non.tls.port` | `5552` | Port number for gRPC non-TLS/HTTP connections.<br><br>**Valid Range:** 1-65535<br><br>**Use Case:** For development environments or when TLS is terminated elsewhere. |
| `trafficparrot.virtualservice.grpc.tls.enabled` | `true` | Controls whether the TLS gRPC server is started.<br><br>**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. |
| `trafficparrot.virtualservice.grpc.non.tls.enabled` | `true` | Controls whether the non-TLS gRPC server is started.<br><br>**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. |

### gRPC TLS/SSL Configuration

| Property Name | Default Value | Description |
| --- | --- | --- |
| `trafficparrot.virtualservice.grpc.requireClientAuthentication` | `true` | Controls whether mutual TLS client authentication is required.<br><br>**Security:** When enabled, clients must present valid certificates for authentication. |
| `trafficparrot.virtualservice.grpc.serverTrustPemUrl` | `classpath:certificates/ grpc/ca.pem` | Path to server's trusted CA certificates for TLS.<br><br>**Format:** PEM format certificate file<br><br>**Usage:** Validates client certificates when mutual TLS is enabled. |
| `trafficparrot.virtualservice.grpc.serverPemUrl` | `classpath:certificates/ grpc/server.pem` | Path to server's certificate file for TLS.<br><br>**Format:** PEM format certificate file<br><br>**Usage:** Server's public certificate for TLS connections. |
| `trafficparrot.virtualservice.grpc.serverKeyUrl` | `classpath:certificates/ grpc/server.key` | Path to server's private key file for TLS.<br><br>**Format:** PEM format private key file<br><br>**Security:** Keep this file secure and private. |
| `trafficparrot.virtualservice.grpc.clientTrustPemUrl` | `classpath:certificates/ grpc/ca.pem` | Path to client's trusted CA certificates for TLS.<br><br>**Usage:** For validating server certificates when making outbound gRPC calls. |
| `trafficparrot.virtualservice.grpc.clientPemUrl` | `classpath:certificates/ grpc/client.pem` | Path to client's certificate file for TLS.<br><br>**Usage:** Client certificate for mutual TLS authentication. |
| `trafficparrot.virtualservice.grpc.clientKeyUrl` | `classpath:certificates/ grpc/client.key` | Path to client's private key file for TLS.<br><br>**Usage:** Client private key for mutual TLS authentication. |
| `trafficparrot.virtualservice.grpc.clientOverrideAuthority` | `foo.test.google.fr` | Authority hostname override for client connections.<br><br>**Use Case:** Useful for testing with self-signed certificates or when hostname doesn't match certificate. |
| `trafficparrot.virtualservice.grpc.client.forceAlwaysTls` | `false` | Controls whether outbound gRPC client connections always use TLS, regardless of the target URL scheme.<br><br>**Use Case:** Set to `true` to force TLS for environments where plain-text gRPC must never be used. |

### gRPC Threading Configuration

| Property Name | Default Value | Description |
| --- | --- | --- |
| `trafficparrot.virtualservice.grpc.server.boss.threads` | `DOUBLE_NUMBER_OF_ PROCESSORS` | Number of Netty boss threads for gRPC server.<br><br>**Values:** `DOUBLE_NUMBER_OF_PROCESSORS`, `NUMBER_OF_PROCESSORS`, or specific integer<br><br>**Performance:** Boss threads handle connection acceptance. |
| `trafficparrot.virtualservice.grpc.server.worker.threads` | `DOUBLE_NUMBER_OF_ PROCESSORS` | Number of Netty worker threads for gRPC server.<br><br>**Values:** `DOUBLE_NUMBER_OF_PROCESSORS`, `NUMBER_OF_PROCESSORS`, or specific integer<br><br>**Performance:** Worker threads handle I/O operations. |
| `trafficparrot.virtualservice.grpc.server.receiveThreads` | `DOUBLE_NUMBER_OF_ PROCESSORS` | Number of threads for receiving gRPC messages.<br><br>**Performance:** Dedicated threads for message reception processing. |
| `trafficparrot.virtualservice.grpc.server.sendThreads` | `DOUBLE_NUMBER_OF_ PROCESSORS` | Number of threads for sending gRPC messages.<br><br>**Performance:** Dedicated threads for message transmission processing. |

### gRPC Performance and Caching

| Property Name | Default Value | Description |
| --- | --- | --- |
| `trafficparrot.virtualservice.grpc.server.replay.maxMessagesWaitingToBeSent` | `1000` | Maximum number of messages that can wait in the send queue.<br><br>**Performance:** Higher values allow more message buffering but use more memory. |
| `trafficparrot.virtualservice.grpc.server.replay.proto.cache.milliseconds` | `0` | Duration in milliseconds for caching protobuf definitions.<br><br>**Performance Profile:** 1200000 (20 minutes)<br><br>**Performance:** Caching reduces file I/O for proto definitions. |
| `trafficparrot.virtualservice.grpc.server.replay.proto.cache.populate.on.startup` | `false` | Whether to populate the proto cache during startup.<br><br>**Performance Profile:** true<br><br>**Trade-off:** Slower startup for faster runtime performance. |
| `trafficparrot.virtualservice.grpc.server.warmup.on.startup` | `true` | Whether to warm up gRPC server components during startup.<br><br>**Performance:** Pre-initializes components for better first-request performance. |

### gRPC Message Processing

| Property Name | Default Value | Description |
| --- | --- | --- |
| `trafficparrot.virtualservice.grpc.exclude.request.headers.from.matching` | `content-type, user-agent, grpc-accept-encoding` | Comma-separated list of headers to exclude from request matching.<br><br>**Use Case:** Excludes volatile headers that shouldn't affect stubbing behavior. |
| `trafficparrot.virtualservice.grpc.message.field.naming` | `CAMEL_CASE` | Controls how protobuf field names are rendered in JSON.<br><br>**Values:**<br><br>- `ORIGINAL` - Preserve proto field names (e.g., input_name)<br>- `CAMEL_CASE` - Convert to camelCase (e.g., inputName) |
| `trafficparrot.virtualservice.grpc.openapi2proto.plugin.location` | `AUTO_DETECT` | Location of the openapi2proto plugin binary.<br><br>**Values:**<br><br>- `AUTO_DETECT` - Searches plugins directory, $PATH, and $HOME/go/bin<br>- Specific path - e.g., `C:\example\openapi2proto.exe` |

### gRPC Schema Validation

| Property Name | Default Value | Description |
| --- | --- | --- |
| `trafficparrot.virtualservice.grpc.check.mapping.schema.on.startup` | `false` | Whether to validate gRPC mappings against proto schemas during startup.<br><br>**Use Case:** Set to `true` to prevent startup with invalid mappings.<br><br>**Example:** Prevents startup if mapping references non-existent proto method. |
| `trafficparrot.virtualservice.grpc.check.mapping.schema.allow.missing.fields` | `false` | Whether to allow mappings with missing fields during schema validation.<br><br>**Dependencies:** Works with `check.mapping.schema.on.startup`<br><br>**Flexibility:** When `true`, allows partial field coverage in mappings. |

### gRPC File Naming Templates

| Property Name | Default Value | Description |
| --- | --- | --- |
| `trafficparrot.virtualservice.grpc.saved.mapping.file.name.template` | `{{ mapping.package }}. {{ countGrpcMappings package=mapping.package offset=1 format='%02d' }}. {{ mapping.service }}- {{ mapping.method }}[ {{ mapping.status.name }}]` | Template for generating gRPC mapping file names.<br><br>**Available properties:** `mapping.id`, `mapping.package`, `mapping.service`, `mapping.method`, `mapping.isSuccess`, `mapping.status.name`, `mapping.status.code`<br><br>**Available commands:** `countGrpcMappings` with parameters for package, service, method, success, offset, format |
| `trafficparrot.virtualservice.grpc.saved.mapping.file.name.collision.suffix.template` | `-{{ mapping.id }}` | Template for suffix when mapping file names collide.<br><br>**Use Case:** Appended when generated file name already exists.<br><br>**Available properties:** Same as main template plus additional Handlebars helpers. |

<a id="websocket-properties"></a>
## WebSocket System Simulation Properties

These properties configure the WebSocket simulator (also referred to as a virtual service or API mock). It answers each inbound text frame from WebSocket mappings, is **off by default**, and is documented on the [WebSocket page](https://trafficparrot.com/documentation/5.65.x/websocket.html). WebSocket clients connect to the main virtual service HTTP port using `Connection: Upgrade`; there is no separate WebSocket port. Mappings are loaded from `websocket-mappings/` in the selected scenario, or at the traffic files root when no scenario is selected.

| Property Name | Default Value | Description |
| --- | --- | --- |
| `trafficparrot.websocket.enabled` | `false` | Master switch that controls whether the WebSocket simulator starts.<br><br>**Values:**<br><br>- `false` (default) - WebSocket upgrade requests are not accepted.<br>- `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. |

<a id="openapi-properties"></a>
## OpenAPI Integration Properties

These properties control OpenAPI specification import, validation, and processing functionality.

| Property Name | Default Value | Description |
| --- | --- | --- |
| `trafficparrot.openapi.import.mode` | `MATCHING_RESPONSE_CODE` | Controls how OpenAPI specifications are imported into WireMock mappings.<br><br>**Values:**<br><br>- `MATCHING_RESPONSE_CODE` - Uses response status in request matchers convention<br>- `SKELETON` - Templates the mapping with the request and response structure<br>- `SELECT_RESPONSE_STATUS` - Uses generic matcher, relies on x-traffic-parrot-select-response-status header |
| `trafficparrot.openapi.import.on.startup` | `false` | Whether OpenAPI specifications should be automatically imported during startup.<br><br>**Use Case:** Useful for automated environments to pre-load API specifications.<br><br>**Dependencies:** Requires OpenAPI files in the configured openapi directory. |
| `trafficparrot.openapi.request.validation.mode` | `OFF` | Controls OpenAPI request validation behavior.<br><br>**Values:**<br><br>- `OFF` - Turns off validation completely<br>- `DEFAULT_VALIDATION` - Turns on validation and provides default responses when not annotated<br>- `ONLY_ANNOTATED` - Turns on validation only for annotated specifications |
| `trafficparrot.openapi.skeletons.mode` | `SKELETON` | Controls how skeleton mappings are generated from OpenAPI specifications.<br><br>**Values:** Same as `trafficparrot.openapi.import.mode`<br><br>**Use Case:** Specifically for generating template/skeleton responses rather than full imports. |
| `trafficparrot.virtualservice.openapi.check.mapping.schema.on.startup` | `false` | Whether to validate HTTP mappings against OpenAPI specifications during startup.<br><br>**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.<br><br>**Dependencies:** Requires OpenAPI files in `scenarios/{scenario}/openapi/`. See the [OpenAPI schema check](https://trafficparrot.com/documentation/5.65.x/http.html#openapi-schema-check) documentation for details. |
| `trafficparrot.openapi.vendor.extension.prefix` | `x-traffic-parrot` | Defines the prefix for vendor-specific OpenAPI extensions used by Traffic Parrot.<br><br>**Examples:**<br><br>- `x-traffic-parrot-validation` - Custom validation rules<br>- `x-traffic-parrot-select-response-status` - Response selection headers<br><br>**Critical:** Required for validation system and custom extensions to work properly. |

<a id="ibmmq-properties"></a>
## IBM MQ Native Integration Properties

These properties configure native IBM MQ integration including logging, performance monitoring, and startup automation.

| Property Name | Default Value | Description |
| --- | --- | --- |
| `trafficparrot.ibmmq.cicsBridge.enabled` | `false` | 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.<br><br>**Performance Profile:** false<br><br>**Use Case:** Set to `true` to stand in for the CICS bridge. See [CICS over IBM MQ](https://trafficparrot.com/documentation/5.65.x/cics.html). |
| `trafficparrot.ibmmq.logger.logMessageBody` | `true` | Controls whether IBM MQ message bodies are logged.<br><br>**Performance Profile:** false<br><br>**Use Case:** Enable for debugging message content, disable for performance. |
| `trafficparrot.ibmmq.logger.logMessageBodyAsPrintableCharacters` | `false` | Controls whether message bodies are logged as printable characters only.<br><br>**Use Case:** When enabled, filters binary content to only printable characters for log readability. |
| `trafficparrot.ibmmq.monitorPerformance` | `false` | Enables performance monitoring for IBM MQ operations.<br><br>**Output:** Logs "Total processing time" metrics for IBM MQ message processing.<br><br>**Use Case:** Enable for performance analysis and troubleshooting. |
| `trafficparrot.ibmmq.skipHeadersInRequestMessageBodyWhenMatching` | `true` | Controls whether headers are included in request message body during matching.<br><br>**Impact:** When `true`, excludes RFH headers from message body content when matching requests to recorded mappings.<br><br>**Use Case:** Improves matching accuracy by ignoring volatile header content. |
| `trafficparrot.ibmmq.start.queue.replay.on.startup.script` | `(empty)` | Path to script file for IBM MQ queue replay on startup.<br><br>**Format:** File path or classpath URL to script file<br><br>**Example:** `classpath:start-ibmmq-queue-replay-on-startup.txt`<br><br>**Use Case:** Automate IBM MQ queue replay operations when Traffic Parrot starts. |

<a id="jms-properties"></a>
## JMS System Simulation Properties

These properties configure JMS message simulation with replay capabilities and startup automation. JMS simulators (virtual services/API mocks) can simulate message queues and topics.

| Property Name | Default Value | Description |
| --- | --- | --- |
| `trafficparrot.jms.start.queue.replay.on.startup` | `false` | Enables automatic JMS queue replay on startup.<br><br>**Dependencies:** Requires valid connection IDs for consumer and producer.<br><br>**Use Case:** Automate JMS message replay without manual intervention. |
| `trafficparrot.jms.start.queue.replay.on.startup.consumeRequestsFromConnectionId` | `<specify a connectionId from jms-connections.json>` | Specifies connection ID for consuming JMS requests on startup.<br><br>**Format:** Valid connection ID from jms-connections.json<br><br>**Performance Profile:** not-used<br><br>**Dependencies:** Requires `trafficparrot.jms.start.queue.replay.on.startup=true` |
| `trafficparrot.jms.start.queue.replay.on.startup.replayResponsesToConnectionId` | `<specify a connectionId from jms-connections.json>` | Specifies connection ID for sending JMS responses on startup.<br><br>**Format:** Valid connection ID from jms-connections.json<br><br>**Performance Profile:** not-used<br><br>**Dependencies:** Requires `trafficparrot.jms.start.queue.replay.on.startup=true` |
| `trafficparrot.jms.monitorPerformance` | `false` | Enables performance monitoring for JMS operations.<br><br>**Output:** Logs "Total processing time" metrics for JMS message processing.<br><br>**Use Case:** Enable for performance analysis and troubleshooting. |
| `trafficparrot.jms.delivery.mode` | `PERSISTENT` | JMS delivery mode used when the simulator sends response or replayed messages.<br><br>**Allowed Values:** `PERSISTENT`, `NON_PERSISTENT`, or a numeric `javax.jms.DeliveryMode` / `jakarta.jms.DeliveryMode` constant (`2` = persistent, `1` = non-persistent).<br><br>**Use Case:** Set to `NON_PERSISTENT` for higher throughput when message durability is not required. |
| `trafficparrot.messaging.diagnostics.enabled` | `false` | Enables near-miss diagnostics for unmatched JMS, IBM MQ, and File messaging requests, similar to the HTTP [near-miss diagnosis](https://trafficparrot.com/documentation/5.65.x/http.html#request-log-near-misses) feature. When enabled, unmatched incoming messages and their closest mappings are recorded so they can be inspected in the messaging request log.<br><br>**Use Case:** Turn on while diagnosing mapping mismatches during stub development; leave off in performance-sensitive environments. |
| `trafficparrot.virtualservice.messaging.check.mapping.schema.on.startup` | `false` | Whether to check JMS, native IBM® MQ and file message mappings against their [mapping schemas](https://trafficparrot.com/documentation/5.65.x/generate-mocks-with-ai-agent.html#agents-md) during startup.<br><br>**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`](https://trafficparrot.com/documentation/5.65.x/http.html#validate-cli-mapping-schema) runs the same check without starting the server, whatever this property says. |
| `trafficparrot.activemq.broker.memory.limit.mb` | `128` | Memory limit (MB) for the embedded ActiveMQ internal broker used by the JMS simulator.<br><br>**Use Case:** Increase when stubbing high-throughput JMS scenarios that buffer many in-flight messages. |
| `trafficparrot.activemq.broker.temp.limit.mb` | `256` | Temporary storage limit (MB) for the embedded ActiveMQ internal broker, used when memory-resident messages spill to temporary disk storage. |
| `trafficparrot.activemq.broker.store.limit.mb` | `256` | Persistent message store limit (MB) for the embedded ActiveMQ internal broker. |
| `trafficparrot.activemq.broker.scheduler.limit.mb` | `256` | Scheduler store limit (MB) for the embedded ActiveMQ internal broker, used for delayed and scheduled message delivery. |

<a id="file-properties"></a>
## File Messaging Properties

These properties configure file message simulation over [SFTP, FTP and Local File System connections](https://trafficparrot.com/documentation/5.65.x/filemessage.html#configuration), and the [embedded SFTP server](https://trafficparrot.com/documentation/5.65.x/filemessage.html#sftp-server).

| Property Name | Default Value | Description |
| --- | --- | --- |
| `trafficparrot.file.remote.temporaryFileNames` | `*.tmp,*.part,*.filepart` | 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.<br><br>**Use Case:** A client that uploads under `.inprogress` names: set `*.inprogress`. See [How files on SFTP and FTP servers are picked up](https://trafficparrot.com/documentation/5.65.x/filemessage.html#remote-file-pickup). |
| `trafficparrot.file.sftp.server.enabled` | `false` | Whether Traffic Parrot runs the [embedded SFTP server](https://trafficparrot.com/documentation/5.65.x/filemessage.html#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.<br><br>**Use Case:** Virtualise a file gateway without an SFTP server of your own. |
| `trafficparrot.file.sftp.server.port` | `8022` | The port the embedded SFTP server listens on. A port already in use stops Traffic Parrot starting.<br><br>**Use Case:** A client that can only connect on port `22`: set `22`, and run Traffic Parrot with the privilege that port needs. |
| `trafficparrot.file.sftp.server.bindAddress` | `0.0.0.0` | The address the embedded SFTP server listens on. The default accepts connections on every interface.<br><br>**Use Case:** Serve clients on the same machine only: set `127.0.0.1`. |
| `trafficparrot.file.sftp.server.rootDirectory` | `sftp-server-root` | 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. |
| `trafficparrot.file.sftp.server.usersFile` | `sftp-server-users.json` | 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](https://trafficparrot.com/documentation/5.65.x/filemessage.html#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. |
| `trafficparrot.file.sftp.server.hostKeyFile` | `sftp-server-host.key` | 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. |

<a id="extension-system-properties"></a>
## Extension System Properties

These properties control Traffic Parrot's extensible architecture with customizable components for different protocols.

### HTTP Extensions

| Property Name | Default Value | Description |
| --- | --- | --- |
| `trafficparrot.http.handlebars.enabled` | `true` | Controls whether Handlebars template processing is enabled for HTTP responses.<br><br>**Performance Profile:** false<br><br>**Dependencies:** Works with `trafficparrot.http.handlebars.helpers` |
| `trafficparrot.http.handlebars.helpers` | `com.trafficparrot.http.handlebars.CsvDataFile, com.trafficparrot.http.handlebars.HttpNow, com.trafficparrot.http.handlebars.RandomDouble, com.trafficparrot.http.handlebars.RandomInteger, com.trafficparrot.http.handlebars.RandomString, com.trafficparrot.http.handlebars.RandomUUID, com.trafficparrot.http.handlebars.image.Image, com.trafficparrot.handlebars.script.Evaluate, com.trafficparrot.handlebars.script.ExecuteProcess` | Comma-separated list of Handlebars helper class names for HTTP.<br><br>**Available Helpers:**<br><br>- `CsvDataFile` - Reads data from CSV files using coordinates<br>- `HttpNow` - Provides current date/time functionality<br>- `RandomDouble` - Generates random double values<br>- `RandomInteger` - Generates random integer values<br>- `RandomString` - Generates random strings (up to 10,000 characters)<br>- `RandomUUID` - Generates random UUIDs<br>- `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](https://trafficparrot.com/documentation/5.65.x/dynamic.html#base64-decode-body-transformer) so the response carries the raw PNG; see the [`{{image}}` helper](https://trafficparrot.com/documentation/5.65.x/dynamic.html#image-helper)<br>- `Evaluate` - Executes script expressions<br>- `ExecuteProcess` - Runs an external process on the host and inserts its output. Remove it from this list to disable the helper |
| `trafficparrot.http.cleanup.enabled` | `true` | Controls whether the **Cleanup** entry appears in the HTTP navigation dropdown, linking to the HTTP Mock Cleanup page that consolidates and prunes recorded mappings.<br><br>**Performance Profile:** false<br><br>**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. |
| <a id="http-mappings-persistent-by-default"></a>`trafficparrot.http.mappings.persistentByDefault` | `false` | Whether a mapping added through the WireMock admin API (`POST /api/http/__admin/mappings`, a WireMock client's `stubFor`, the Testcontainers client's `stub()`) without `"persistent": true` is written to a file under `mappings/`.<br><br>**Performance Profile:** false<br><br>**Use Case:** Leave it `false` for WireMock's behaviour: such a mapping is held in memory, serves at once, is marked **Not saved** in the HTTP mappings list, where that marker is a button that writes it to a file, and is gone on reset or restart. Set to `true` to write every mapping added through the API to a file. Mappings added in the web user interface, by import, by recording and by the MCP tools are always written to files, whatever this property says. See [A clean start for every test](https://trafficparrot.com/documentation/5.65.x/user_guide.html#junit-spring-tests-reset). |
| `trafficparrot.http.externalprocess.enabled` | `false` | Enables the [`external-process`](https://trafficparrot.com/documentation/5.65.x/dynamic.html#external-process-transformer) HTTP response transformer, which passes the response through a user-supplied executable (the "middleware") over a JSON envelope on stdin/stdout.<br><br>**Performance Profile:** false<br><br>**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.<br><br>**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](https://trafficparrot.com/documentation/5.65.x/dynamic.html#external-process-security). |
| `trafficparrot.http.externalprocess.allowedDir` | `(empty)` | A single directory that the [`external-process`](https://trafficparrot.com/documentation/5.65.x/dynamic.html#external-process-transformer) transformer is restricted to. Only executables whose canonical (symlink-resolved) path is under this directory may be invoked.<br><br>**Performance Profile:** (empty)<br><br>**Use Case:** Confine external-process middleware to a dedicated, operator-vetted directory of scripts.<br><br>**Note:** an empty value means nothing is allowed, even when `trafficparrot.http.externalprocess.enabled=true`; both must be set for the feature to run. |
| `trafficparrot.http.importfromurl.enabled` | `false` | 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.<br><br>**Performance Profile:** false<br><br>**Use Case:** Allow operators to opt in to fetching specifications over the network. While `false`, no URL can be imported.<br><br>**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. |
| `trafficparrot.http.importfromurl.allowedHosts` | `(empty)` | 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.<br><br>**Performance Profile:** (empty)<br><br>**Use Case:** Confine import-from-URL fetches to a vetted set of hosts.<br><br>**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. |
| `trafficparrot.http.jwt.enabled` | `true` | Enables JWT (JSON Web Token) processing capabilities for HTTP.<br><br>**Performance Profile:** false<br><br>**Use Case:** For JWT token validation and processing in HTTP requests. |
| `trafficparrot.http.modify.response.enabled` | `true` | Enables HTTP response modification capabilities.<br><br>**Performance Profile:** false<br><br>**Use Case:** Allows dynamic modification of HTTP responses before sending to clients. |
| `trafficparrot.http.optionsResponse.enabled` | `true` | Enables automatic HTTP OPTIONS response handling.<br><br>**Performance Profile:** false<br><br>**Use Case:** Automatically handles CORS preflight requests. |
| `trafficparrot.http.soap.message.signer.enabled` | `true` | Enables SOAP message signing capabilities.<br><br>**Performance Profile:** false<br><br>**Use Case:** For WS-Security SOAP message signing functionality. |
| `trafficparrot.http.webhooks.enabled` | `true` | Enables webhook functionality for HTTP responses.<br><br>**Performance Profile:** false<br><br>**Use Case:** Allows HTTP responses to trigger outbound webhook calls. |

### Response Transformers

| Property Name | Default Value | Description |
| --- | --- | --- |
| `trafficparrot.http.responsetransformers` | `com.trafficparrot.virtualservice.extensions.responsetransformer.UpdateContentLengthTransformer,com.trafficparrot.virtualservice.extensions.responsetransformer.HlsStreamTransformer` | Comma-separated list of response transformer class names for HTTP simulator (mock)s.<br><br>A class in the list that cannot be loaded or created when a WireMock server starts (it is not on the classpath, it has neither a public no-argument constructor nor a public constructor taking a `TrafficParrotServices`, or its constructor throws) is left out of that server, and the other extensions and every mapping are served. The [log](https://trafficparrot.com/documentation/5.65.x/logging.html) says why, the HTTP mappings list shows it in a notice, and `GET /http/management/skippedExtensions` lists it, with the servers it applies to when that is not every one. See [Traffic Parrot started but one of my mocks or extensions is missing](https://trafficparrot.com/documentation/5.65.x/logging.html#left-out-at-start).<br><br>**Performance Profile:** (empty)<br><br>**Default Transformers:**<br><br>- `UpdateContentLengthTransformer` - Automatically updates Content-Length headers to match response body size<br>- `HlsStreamTransformer` - Serves HLS video streaming content (`.m3u8` playlists and `.ts` segments). See [built-in response transformers](https://trafficparrot.com/documentation/5.65.x/dynamic.html#built-in-transformers) for details.<br><br>**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.<br><br>**Examples:**<br><br>- Single: `com.example.MyTransformer`<br>- Multiple: `com.example.TransformerA,com.example.TransformerB`<br>- Disabled: (empty) |
| `trafficparrot.jms.responsetransformers` | `com.trafficparrot.messaging.jms.JmsPassthroughMessage` | Comma-separated list of response transformer class names for JMS.<br><br>**Performance Profile:** (empty)<br><br>**Default Transformer:** `JmsPassthroughMessage` - Passes JMS messages through without modification |
| `trafficparrot.ibmmq.responsetransformers` | `(empty)` | Comma-separated list of response transformer class names for IBM MQ.<br><br>**Use Case:** Custom transformation of IBM MQ messages before sending responses. |
| `trafficparrot.file.responsetransformers` | `(empty)` | Comma-separated list of response transformer class names for file-based messaging.<br><br>**Use Case:** Custom transformation of file messages before processing. |

### Messaging Protocol Handlebars

| Property Name | Default Value | Description |
| --- | --- | --- |
| `trafficparrot.jms.handlebars.enabled` | `true` | Controls Handlebars template processing for JMS messages.<br><br>**Performance Profile:** false |
| `trafficparrot.jms.handlebars.helpers` | `com.trafficparrot.http.handlebars.RandomDouble, com.trafficparrot.http.handlebars.RandomInteger, com.trafficparrot.http.handlebars.RandomString, com.trafficparrot.http.handlebars.RandomUUID, com.trafficparrot.handlebars.script.Evaluate, com.trafficparrot.handlebars.script.ExecuteProcess` | JMS-specific Handlebars helpers (excludes CSV and HTTP-specific helpers).<br><br>**Performance Profile:** (empty) |
| `trafficparrot.ibmmq.handlebars.enabled` | `true` | Controls Handlebars template processing for IBM MQ messages.<br><br>**Performance Profile:** false |
| `trafficparrot.ibmmq.handlebars.helpers` | `com.trafficparrot.http.handlebars.RandomDouble, com.trafficparrot.http.handlebars.RandomInteger, com.trafficparrot.http.handlebars.RandomString, com.trafficparrot.http.handlebars.RandomUUID, com.trafficparrot.handlebars.script.Evaluate, com.trafficparrot.handlebars.script.ExecuteProcess` | IBM MQ-specific Handlebars helpers (same as JMS).<br><br>**Performance Profile:** (empty) |
| `trafficparrot.file.handlebars.enabled` | `true` | Controls Handlebars template processing for file-based messaging.<br><br>**Performance Profile:** false |
| `trafficparrot.file.handlebars.helpers` | `com.trafficparrot.http.handlebars.RandomDouble, com.trafficparrot.http.handlebars.RandomInteger, com.trafficparrot.http.handlebars.RandomString, com.trafficparrot.http.handlebars.RandomUUID, com.trafficparrot.handlebars.script.Evaluate, com.trafficparrot.handlebars.script.ExecuteProcess` | File messaging-specific Handlebars helpers.<br><br>**Performance Profile:** (empty) |

<a id="enterprise-properties"></a>
## Enterprise Features

These properties configure enterprise-ready authentication, licensing, and monitoring capabilities.

### Okta SSO Integration

| Property Name | Default Value | Description |
| --- | --- | --- |
| `trafficparrot.okta.enabled` | `false` | Master switch to enable/disable Okta SSO functionality.<br><br>**Impact:** When enabled, adds OAuth2/OIDC authentication to the web UI.<br><br>**Flow:** Implements Authorization Code flow with session-based and Bearer token authentication. |
| `trafficparrot.okta.clientId` | `some_client_id` | OAuth2 client identifier for the Traffic Parrot application registered in Okta.<br><br>**Usage:** Used in authorization URL construction and token exchange requests.<br><br>**Required:** Application will fail if not properly configured. |
| `trafficparrot.okta.clientSecret` | `some_client_secret` | OAuth2 client secret for authenticating with Okta token endpoint.<br><br>**Security:** Combined with clientId for Basic Auth in token exchange.<br><br>**Storage:** Sensitive credential that should be securely stored. |
| `trafficparrot.okta.oktaAuthorizeUri` | `https://${yourOktaDomain}/ oauth2/default/v1/authorize` | Okta authorization endpoint for OAuth2 Authorization Code flow.<br><br>**Parameters:** Includes client_id, response_type=code, scope=openid, redirect_uri, state<br><br>**Format:** Must be valid HTTPS URL pointing to Okta authorization server. |
| `trafficparrot.okta.oktaTokenUri` | `https://${yourOktaDomain}/ oauth2/default/v1/token` | Okta token endpoint for exchanging authorization codes for access tokens.<br><br>**Usage:** HTTP POST request with grant_type=authorization_code, redirect_uri, code<br><br>**Response:** Extracts access_token for JWT validation. |
| `trafficparrot.okta.oktaIssuerUri` | `https://${yourOktaDomain}/ oauth2/default` | Okta issuer URI for JWT token validation.<br><br>**JWT Validation:** Validates JWT 'iss' claim matches this value.<br><br>**Security:** Part of JWT signature verification process. |
| `trafficparrot.okta.oktaAudience` | `api://default` | Expected audience claim in JWT access tokens.<br><br>**JWT Validation:** Validates JWT 'aud' claim contains this value.<br><br>**Security:** Ensures tokens are intended for this application. |
| `trafficparrot.okta.oktaRedirectUri` | `https://some-TP-deployment-uri` | OAuth2 redirect URI where Okta returns authorization codes.<br><br>**Configuration:** Must match exactly what's configured in Okta application settings.<br><br>**Usage:** URL-encoded in authorization requests and token exchange requests. |

### License Management

| Property Name | Default Value | Description |
| --- | --- | --- |
| `trafficparrot.license.usage.server` | `DEFAULT` | Specifies license server URL for on-premise license validation.<br><br>**Values:**<br><br>- `DEFAULT` - Use default cloud-based licensing<br>- `host:port` - HTTP license server<br>- `https://host:port` - HTTPS license server<br><br>**Use Case:** For on-premise licenses with local license servers. |
| `trafficparrot.license.usage.custom.headers` | `NONE` | Custom HTTP headers for license server communications.<br><br>**Format:** Comma-separated Key:Value pairs<br><br>**Example:** `Authorization:Bearer token,Environment:Test`<br><br>**Use Case:** Add authentication, routing, or other custom headers to license requests. |

### JMX Monitoring

| Property Name | Default Value | Description |
| --- | --- | --- |
| `trafficparrot.virtualservice.jmx.enabled` | `false` | Enables JMX monitoring for the simulator simulator (virtual service/mock).<br><br>**Use Case:** Enable for remote monitoring and management using JMX tools.<br><br>**MBeans:** Exposes management beans for simulator simulator (virtual service/mock) monitoring. |
| `trafficparrot.virtualservice.jmx.port` | `8084` | Specifies the port for simulator (virtual service/mock) JMX connector.<br><br>**Valid Range:** 1-65535<br><br>**Dependencies:** Requires `trafficparrot.virtualservice.jmx.enabled=true`<br><br>**Access:** JMX management interface available on this port. |

### Debug Logging Configuration

To enable debug logging for inspecting issues with HTTP requests and responses, add the following log4j configurations to your `trafficparrotserver.log4j.properties` file (as specified in the `jvm.args` file with `-Dtrafficparrotserver.logging.properties.filename=trafficparrotserver.log4j.properties`):

#### Copy and paste this entire block into your log4j properties file:

```properties
# Debug logging for HTTP requests and responses
log4j.logger.WireMock=DEBUG
log4j.logger.com.github.tomakehurst.wiremock.http.ProxyResponseRenderer=DEBUG
log4j.logger.com.github.tomakehurst.wiremock.http=DEBUG
log4j.logger.com.github.tomakehurst.wiremock.servlet=DEBUG
log4j.logger.org.eclipse.jetty.server.HttpChannel=DEBUG
log4j.logger.org.eclipse.jetty.server.HttpConnection=DEBUG
log4j.logger.org.eclipse.jetty.http.HttpParser=DEBUG
log4j.logger.org.eclipse.jetty.http.HttpGenerator=DEBUG
log4j.logger.org.eclipse.jetty.server.Request=DEBUG
log4j.logger.org.eclipse.jetty.server.Response=DEBUG
log4j.logger.org.apache.hc=DEBUG
log4j.logger.org.apache.hc.client5.http.headers=DEBUG
log4j.logger.org.apache.hc.client5.http.wire=DEBUG
```

#### Individual Logger Descriptions:

| Logger Configuration | Description |
| --- | --- |
| `log4j.logger.WireMock=DEBUG` | Enable debug logging for WireMock core functionality |
| `log4j.logger.com.github.tomakehurst.wiremock.http.ProxyResponseRenderer=DEBUG` | Debug logging for proxy response rendering |
| `log4j.logger.com.github.tomakehurst.wiremock.http=DEBUG` | Debug logging for WireMock HTTP handling |
| `log4j.logger.com.github.tomakehurst.wiremock.servlet=DEBUG` | Debug logging for WireMock servlet operations |
| `log4j.logger.org.eclipse.jetty.server.HttpChannel=DEBUG` | Debug logging for Jetty HTTP channel processing |
| `log4j.logger.org.eclipse.jetty.server.HttpConnection=DEBUG` | Debug logging for Jetty HTTP connections |
| `log4j.logger.org.eclipse.jetty.http.HttpParser=DEBUG` | Debug logging for Jetty HTTP parsing |
| `log4j.logger.org.eclipse.jetty.http.HttpGenerator=DEBUG` | Debug logging for Jetty HTTP generation |
| `log4j.logger.org.eclipse.jetty.server.Request=DEBUG` | Debug logging for Jetty request processing |
| `log4j.logger.org.eclipse.jetty.server.Response=DEBUG` | Debug logging for Jetty response processing |
| `log4j.logger.org.apache.hc=DEBUG` | Debug logging for Apache HttpClient |
| `log4j.logger.org.apache.hc.client5.http.headers=DEBUG` | Debug logging for HttpClient headers |
| `log4j.logger.org.apache.hc.client5.http.wire=DEBUG` | Debug logging for HttpClient wire-level communication (raw HTTP data) |

> #### Performance Impact
>
> Enabling debug logging, especially wire-level logging, will significantly impact performance and generate large log files. Only enable these settings when debugging specific issues and disable them in production environments.

<a id="performance-considerations"></a>
## Performance Profile Considerations

> #### Performance vs Functionality Trade-offs
>
> Traffic Parrot includes a performance profile (`trafficparrot.performance.properties`) that optimizes many properties for high-load scenarios:
>
> ##### Disabled Features (Performance Mode)
>
> - **Extension System:** Most Handlebars helpers, response transformers, JWT processing
> - **Logging:** IBM MQ message body logging, request journaling
> - **Advanced Features:** SOAP signing, webhooks, automatic OPTIONS responses
>
> ##### Optimized Settings (Performance Mode)
>
> - **Thread Pools:** Increased container threads (500 vs 100)
> - **Caching:** Enabled mapping cache (10M ms), Handlebars cache (10K entries)
> - **gRPC:** Optimized proto caching and startup population
> - **CSV Processing:** Enabled indexing and caching for better performance
>
> ##### Recommendations
>
> - **Development:** Use standard configuration for full feature access
> - **Testing:** Standard configuration for comprehensive validation
> - **Test Environment High-Load:** Performance profile for maximum throughput
> - **Test Environment Low-Load:** Standard configuration with selective feature tuning

> #### Performance Testing Guide
>
> For comprehensive performance testing strategies, benchmarking techniques, and optimization tips, see our dedicated [**Performance Testing Guide**](https://trafficparrot.com/documentation/5.65.x/performance_testing.html).