Settings Properties

Properties can be set by:

  1. java code (highest precedence)
  2. system property
  3. property file
  4. environment property (lowest precedence)

The order of precedence means that properties set by java code overrides those set by system properties which overrides property file properties which overrides environment variables.

Some properties need to be set before MockServer starts because they are only read at start-up, for example, nioEventLoopThreadCount.

Other values are read continuously and so can be changed at any time, for example, logLevel.

 

Property File

The property file defaults to filename mockserver.properties in the current working directory of MockServer.

This location of the property file can be changed by setting the mockserver.propertyFile system property or MOCKSERVER_PROPERTY_FILE environment property, for example:

-Dmockserver.propertyFile=/config/mockserver.properties

An example properties file can be found in github, as follows:

###############################
# MockServer & Proxy Settings #
###############################

# Socket & Port Settings

# socket timeout in milliseconds (default 120000)
mockserver.maxSocketTimeout=120000

# Certificate Generation

# dynamically generated CA key pair (if they don't already exist in specified directory)
mockserver.dynamicallyCreateCertificateAuthorityCertificate=true
# save dynamically generated CA key pair in working directory
mockserver.directoryToSaveDynamicSSLCertificate=.
# certificate domain name (default "localhost")
mockserver.sslCertificateDomainName=localhost
# comma separated list of ip addresses for Subject Alternative Name domain names (default empty list)
mockserver.sslSubjectAlternativeNameDomains=www.example.com,www.another.com
# comma separated list of ip addresses for Subject Alternative Name ips (default empty list)
mockserver.sslSubjectAlternativeNameIps=127.0.0.1

# CORS

# enable CORS for MockServer REST API
mockserver.enableCORSForAPI=true
# enable CORS for all responses
mockserver.enableCORSForAllResponses=true
 

Configuration Properties

 

Liveness Configuration:

Path to support HTTP GET requests for status response (also available on PUT /mockserver/status).

If this value is not modified then only PUT /mockserver/status but is a none blank value is provided for this value then GET requests to this path will return the 200 Ok status response showing the MockServer version and bound ports.

A GET request to this path will be matched before any expectation matching or proxying of requests.

Type: string Default: null

Java Code:

ConfigurationProperties.livenessHttpGetPath(String livenessPath)

System Property:

-Dmockserver.livenessHttpGetPath=...

Environment Variable:

MOCKSERVER_LIVENESS_HTTP_GET_PATH=...

Property File:

mockserver.livenessHttpGetPath=...

Example:

-Dmockserver.livenessHttpGetPath="/liveness/probe"
 

Memory Usage Configuration:

Maximum number of expectations held in the in-memory ring buffer

Type: int Default: free heap space in KB / 400

Java Code:

ConfigurationProperties.maxExpectations(int count)

System Property:

-Dmockserver.maxExpectations=...

Environment Variable:

MOCKSERVER_MAX_EXPECTATIONS=...

Property File:

mockserver.maxExpectations=...

Example:

-Dmockserver.maxExpectations="2000"

Maximum number of log entries to hold in memory, this include recorded requests, expectation match failures and other log entries. The lower the log level the more log entries will be captured, particularly at TRACE level logging.

Type: int Default: free heap space in KB / 30

Java Code:

ConfigurationProperties.maxLogEntries(int count)

System Property:

-Dmockserver.maxLogEntries=...

Environment Variable:

MOCKSERVER_MAX_LOG_ENTRIES=...

Property File:

mockserver.maxLogEntries=...

Example:

-Dmockserver.maxLogEntries="2000"

Maximum number of WebSockets held in the in-memory ring buffer

Type: int Default: 1500

Java Code:

ConfigurationProperties.maxWebSocketExpectations(int count)

System Property:

-Dmockserver.maxWebSocketExpectations=...

Environment Variable:

MOCKSERVER_MAX_WEB_SOCKET_EXPECTATIONS=...

Property File:

mockserver.maxWebSocketExpectations=...

Example:

-Dmockserver.maxWebSocketExpectations="2000"

Output JVM memory usage metrics to CSV file periodically called memoryUsage_<yyyy-MM-dd>.csv

Type: boolean Default: false

Java Code:

ConfigurationProperties.outputMemoryUsageCsv(boolean enable)

System Property:

-Dmockserver.outputMemoryUsageCsv=...

Environment Variable:

MOCKSERVER_OUTPUT_MEMORY_USAGE_CSV=...

Property File:

mockserver.outputMemoryUsageCsv=...

Example:

-Dmockserver.outputMemoryUsageCsv="true"
 

Http Request Size Configuration:

Maximum size the first line of an HTTP request

Type: int Default: 4096

Java Code:

ConfigurationProperties.maxInitialLineLength(int length)

System Property:

-Dmockserver.maxInitialLineLength=...

Environment Variable:

MOCKSERVER_MAX_INITIAL_LINE_LENGTH=...

Property File:

mockserver.maxInitialLineLength=...

Example:

-Dmockserver.maxInitialLineLength="8192"

Maximum size HTTP request headers

Type: int Default: 8192

Java Code:

ConfigurationProperties.maxHeaderSize(int size)

System Property:

-Dmockserver.maxHeaderSize=...

Environment Variable:

MOCKSERVER_MAX_HEADER_SIZE=...

Property File:

mockserver.maxHeaderSize=...

Example:

-Dmockserver.maxHeaderSize="16384"

Maximum size of HTTP chunks in request or responses

Type: int Default: 8192

Java Code:

ConfigurationProperties.maxChunkSize(int size)

System Property:

-Dmockserver.maxChunkSize=...

Environment Variable:

MOCKSERVER_MAX_CHUNK_SIZE=...

Property File:

mockserver.maxChunkSize=...

Example:

-Dmockserver.maxChunkSize="16384"
 

Scalability Configuration:

Number of threads for main event loop

These threads are used for fast non-blocking activities such as:

  • reading and de-serialise all requests
  • serialising and writing control plane responses
  • adding, updating or removing expectations
  • verifying requests or request sequences
  • retrieving logs

Expectation actions are handled in a separate thread pool to ensure slow object or class callbacks and response / forward delays do not impact the main event loop.

Type: int Default: 5

Java Code:

ConfigurationProperties.nioEventLoopThreadCount(int count)

System Property:

-Dmockserver.nioEventLoopThreadCount=...

Environment Variable:

MOCKSERVER_NIO_EVENT_LOOP_THREAD_COUNT=...

Property File:

mockserver.nioEventLoopThreadCount=...

Example:

-Dmockserver.nioEventLoopThreadCount="5"

Number of threads for the action handler thread pool

These threads are used for handling actions such as:

  • serialising and writing expectation or proxied responses
  • handling response delays in a non-blocking way (i.e. using a scheduler)
  • executing class callbacks
  • handling method / closure callbacks (using web sockets)

Type: int Default: maximum of 5 or available processors count

Java Code:

ConfigurationProperties.actionHandlerThreadCount(int count)

System Property:

-Dmockserver.actionHandlerThreadCount=...

Environment Variable:

MOCKSERVER_ACTION_HANDLER_THREAD_COUNT=...

Property File:

mockserver.actionHandlerThreadCount=...

Example:

-Dmockserver.actionHandlerThreadCount="5"

Number of threads for each expectation with a method / closure callback (i.e. web socket client) in the org.mockserver.client.MockServerClient

This setting only effects the Java client and how requests each method / closure callbacks it can handle, the default is 5 which should be suitable except in extreme cases.

Type: int Default: 5

Java Code:

ConfigurationProperties.webSocketClientEventLoopThreadCount(int count)

System Property:

-Dmockserver.webSocketClientEventLoopThreadCount=...

Environment Variable:

MOCKSERVER_WEB_SOCKET_CLIENT_EVENT_LOOP_THREAD_COUNT=...

Property File:

mockserver.webSocketClientEventLoopThreadCount=...

Example:

-Dmockserver.webSocketClientEventLoopThreadCount="5"

Number of threads for client event loop when calling downstream

These threads are used for fast non-blocking activities such as, reading and de-serialise all requests and responses

Type: int Default: 5

Java Code:

ConfigurationProperties.clientNioEventLoopThreadCount(int count)

System Property:

-Dmockserver.clientNioEventLoopThreadCount=...

Environment Variable:

MOCKSERVER_CLIENT_NIO_EVENT_LOOP_THREAD_COUNT=...

Property File:

mockserver.clientNioEventLoopThreadCount=...

Example:

-Dmockserver.clientNioEventLoopThreadCount="5"

The the minimum level of logs to record in the event log and to output to system out (if system out log output is not disabled). The lower the log level the more log entries will be captured, particularly at TRACE level logging.

Type: string Default: INFO

Java Code:

ConfigurationProperties.logLevel(String level)

System Property:

-Dmockserver.logLevel=...

Environment Variable:

MOCKSERVER_LOG_LEVEL=...

Property File:

mockserver.logLevel

The log level, which can be TRACE, DEBUG, INFO, WARN, ERROR, OFF, FINEST, FINE, INFO, WARNING, SEVERE

Example:

-Dmockserver.logLevel="DEBUG"

Disable logging to the system output

Type: boolean Default: false

Java Code:

ConfigurationProperties.disableSystemOut(boolean disableSystemOut)

System Property:

-Dmockserver.disableSystemOut=...

Environment Variable:

MOCKSERVER_DISABLE_SYSTEM_OUT=...

Property File:

mockserver.disableSystemOut=...

Example:

-Dmockserver.disableSystemOut="true"

Disable all logging and processing of log events

Type: boolean Default: false

Java Code:

ConfigurationProperties.disableLogging(boolean disableLogging)

System Property:

-Dmockserver.disableLogging=...

Environment Variable:

MOCKSERVER_DISABLE_LOGGING=...

Property File:

mockserver.disableLogging=...

Example:

-Dmockserver.disableLogging="true"
 

Socket Configuration:

Maximum time allowed for a response from a socket

Type: long Default: 20000

Java Code:

ConfigurationProperties.maxSocketTimeout(long milliseconds)

System Property:

-Dmockserver.maxSocketTimeout=...

Environment Variable:

MOCKSERVER_MAX_SOCKET_TIMEOUT=...

Property File:

mockserver.maxSocketTimeout=...

Example:

-Dmockserver.maxSocketTimeout="10000"

Maximum time allowed to connect to a socket

Type: int Default: 20000

Java Code:

ConfigurationProperties.socketConnectionTimeout(int milliseconds)

System Property:

-Dmockserver.socketConnectionTimeout=...

Environment Variable:

MOCKSERVER_SOCKET_CONNECTION_TIMEOUT=...

Property File:

mockserver.socketConnectionTimeout=...

Example:

-Dmockserver.socketConnectionTimeout="10000"

If true socket connections will always be closed after a response is returned, if false connection is only closed if request header indicate connection should be closed.

Type: int Default: false

Java Code:

ConfigurationProperties.alwaysCloseSocketConnections(boolean alwaysClose)

System Property:

-Dmockserver.alwaysCloseSocketConnections=...

Environment Variable:

MOCKSERVER_ALWAYS_CLOSE_SOCKET_CONNECTIONS=...

Property File:

mockserver.alwaysCloseSocketConnections=...

Example:

-Dmockserver.alwaysCloseSocketConnections="true"

If true (the default) request matchers will fail on the first non-matching field, if false request matchers will compare all fields.

This is useful to see all mismatching fields in the log event recording that a request matcher did not match.

Type: string Default: true

Java Code:

ConfigurationProperties.matchersFailFast(boolean enable)

System Property:

-Dmockserver.matchersFailFast=...

Environment Variable:

MOCKSERVER_MATCHERS_FAIL_FAST=...

Property File:

mockserver.matchersFailFast=...

Example:

-Dmockserver.matchersFailFast="false"

If true (the default) the log event recording that a request matcher did not match will include a detailed reason why each non matching field did not match.

Type: string Default: true

Java Code:

ConfigurationProperties.detailedMatchFailures(boolean enable)

System Property:

-Dmockserver.detailedMatchFailures=...

Environment Variable:

MOCKSERVER_DETAILED_MATCH_FAILURES=...

Property File:

mockserver.detailedMatchFailures=...

Example:

-Dmockserver.detailedMatchFailures="false"

If true (the default) the ClientAndServer constructor or static factor methods will open the UI in the default browser when the log level is set to DEBUG.

Type: string Default: false

Java Code:

ConfigurationProperties.launchUIForLogLevelDebug(boolean enable)

System Property:

-Dmockserver.launchUIForLogLevelDebug=...

Environment Variable:

MOCKSERVER_LAUNCH_UI_FOR_LOG_LEVEL_DEBUG=...

Property File:

mockserver.launchUIForLogLevelDebug=...

Example:

-Dmockserver.launchUIForLogLevelDebug="false"

The local IP address to bind to for accepting new socket connections

Type: string Default: 0.0.0.0

Java Code:

ConfigurationProperties.localBoundIP(String localBoundIP)

System Property:

-Dmockserver.localBoundIP=...

Environment Variable:

MOCKSERVER_LOCAL_BOUND_IP=...

Property File:

mockserver.localBoundIP=...

Example:

-Dmockserver.localBoundIP="0.0.0.0"

If true semicolons are treated as a separator for a query parameter string, it false the semicolon is treated as a normal character that is part of a query parameter value.

Type: int Default: true

Java Code:

ConfigurationProperties.useSemicolonAsQueryParameterSeparator(boolean useAsQueryParameterSeparator)

System Property:

-Dmockserver.useSemicolonAsQueryParameterSeparator=...

Environment Variable:

MOCKSERVER_USE_SEMICOLON_AS_QUERY_PARAMETER_SEPARATOR=...

Property File:

mockserver.useSemicolonAsQueryParameterSeparator=...

Example:

-Dmockserver.useSemicolonAsQueryParameterSeparator="true"
 

TLS Configuration:

The following diagram shows where TLS/mTLS configuration settings are used:

MockServer HTTPS & TLS

 

Inbound TLS (for Received Requests)

Dynamic Inbound Certificate Authority X.509 & Private Key

Enable dynamic creation of Certificate Authority X.509 Certificate and Private Key

Enable this property to increase the security of trusting the MockServer Certificate Authority X.509 by ensuring a local dynamic value is used instead of the public value in the MockServer git repo.

These PEM files will be created and saved in the directory specified with configuration property directoryToSaveDynamicSSLCertificate.

A Certificate Authority X.509 Certificate and Private Key will only be created if the files used to save them are not already present. Therefore, if MockServer is re-started multiple times with the same value for directoryToSaveDynamicSSLCertificate. the Certificate Authority X.509 Certificate and Private Key will only be created once.

Type: boolean Default: false

Java Code:

ConfigurationProperties.dynamicallyCreateCertificateAuthorityCertificate(boolean enable)

System Property:

-Dmockserver.dynamicallyCreateCertificateAuthorityCertificate=...

Environment Variable:

MOCKSERVER_DYNAMICALLY_CREATE_CERTIFICATE_AUTHORITY_CERTIFICATE=...

Property File:

mockserver.dynamicallyCreateCertificateAuthorityCertificate=...

Example:

-Dmockserver.dynamicallyCreateCertificateAuthorityCertificate="true"

Directory used to save the dynamically generated Certificate Authority X.509 Certificate and Private Key.

This directory will only be used if MockServer is configured to create a dynamic Certificate Authority X.509 certificate and private key using dynamicallyCreateCertificateAuthorityCertificate.

Type: string Default: null

Java Code:

ConfigurationProperties.directoryToSaveDynamicSSLCertificate(String directoryToSaveDynamicSSLCertificate)

System Property:

-Dmockserver.directoryToSaveDynamicSSLCertificate=...

Environment Variable:

MOCKSERVER_CERTIFICATE_DIRECTORY_TO_SAVE_DYNAMIC_SSL_CERTIFICATE=...

Property File:

mockserver.directoryToSaveDynamicSSLCertificate=...

Example:

-Dmockserver.directoryToSaveDynamicSSLCertificate="/some/existing/path"

Fixed (i.e. Custom) Inbound Certificate Authority X.509 & Private Key

Location of custom file for Certificate Authority for TLS, the private key must be a PKCS#8 PEM file and must match the TLS Certificate Authority X.509 Certificate.

To convert a PKCS#1 PEM file (i.e. default for Bouncy Castle) to a PKCS#8 PEM file the following command can be used: openssl pkcs8 -topk8 -inform PEM -in private_key_PKCS_1.pem -out private_key_PKCS_8.pem -nocrypt

Type: string Default: null

Java Code:

ConfigurationProperties.certificateAuthorityPrivateKey(String certificateAuthorityPrivateKey)

System Property:

-Dmockserver.certificateAuthorityPrivateKey=...

Environment Variable:

MOCKSERVER_CERTIFICATE_AUTHORITY_PRIVATE_KEY=...

Property File:

mockserver.certificateAuthorityPrivateKey=...

Example:

-Dmockserver.certificateAuthorityPrivateKey="true"

Location of custom file for Certificate Authority for TLS, the certificate must be a X.509 PEM file and must match the TLS Certificate Authority Private Key.

Type: string Default: null

Java Code:

ConfigurationProperties.certificateAuthorityCertificate(String certificateAuthorityCertificate)

System Property:

-Dmockserver.certificateAuthorityCertificate=...

Environment Variable:

MOCKSERVER_CERTIFICATE_AUTHORITY_X509_CERTIFICATE=...

Property File:

mockserver.certificateAuthorityCertificate=...

Example:

-Dmockserver.certificateAuthorityCertificate="true"

Dynamic Inbound Private Key & X.509

MockServer dynamically updates the Subject Alternative Name (SAN) values for its TLS certificate to add domain names and IP addresses from request Host headers and Host headers in expectations, this configuration setting disables this automatic update and only uses SAN value provided in TLS Subject Alternative Name Domains and TLS Subject Alternative Name IPs configuration properties.

When this property is enabled the generated X.509 Certificate and Private Key pair are saved to the directoryToSaveDynamicSSLCertificate as Certificate.pem and PKCS8PrivateKey.pem

Type: boolean Default: false

Java Code:

ConfigurationProperties.preventCertificateDynamicUpdate(boolean prevent)

System Property:

-Dmockserver.preventCertificateDynamicUpdate=...

Environment Variable:

MOCKSERVER_PREVENT_CERTIFICATE_DYNAMIC_UPDATE=...

Property File:

mockserver.preventCertificateDynamicUpdate=...

Example:

-Dmockserver.preventCertificateDynamicUpdate="true"

The domain name for auto-generate TLS certificates

Type: string Default: localhost

Java Code:

ConfigurationProperties.sslCertificateDomainName(String domainName)

System Property:

-Dmockserver.sslCertificateDomainName=...

Environment Variable:

MOCKSERVER_SSL_CERTIFICATE_DOMAIN_NAME=...

Property File:

mockserver.sslCertificateDomainName=...

Example:

-Dmockserver.sslCertificateDomainName="localhost"

The Subject Alternative Name (SAN) domain names for auto-generate TLS certificates as a comma separated list

Type: string Default: localhost

Java Code:

ConfigurationProperties.addSslSubjectAlternativeNameDomains(String... additionalSubjectAlternativeNameDomains)
or
ConfigurationProperties.clearSslSubjectAlternativeNameDomains()

System Property:

-Dmockserver.sslSubjectAlternativeNameDomains=...

Environment Variable:

MOCKSERVER_SSL_SUBJECT_ALTERNATIVE_NAME_DOMAINS=...

Property File:

mockserver.sslSubjectAlternativeNameDomains=...

Example:

-Dmockserver.sslSubjectAlternativeNameDomains="localhost,www.foo.bar"

The Subject Alternative Name (SAN) IP addresses for auto-generate TLS certificates as a comma separated list

Type: string Default: 127.0.0.1,0.0.0.0

Java Code:

ConfigurationProperties.addSslSubjectAlternativeNameIps(String... additionalSubjectAlternativeNameIps)
or
ConfigurationProperties.clearSslSubjectAlternativeNameIps()

System Property:

-Dmockserver.sslSubjectAlternativeNameIps=...

Environment Variable:

MOCKSERVER_SSL_SUBJECT_ALTERNATIVE_NAME_IPS=...

Property File:

mockserver.sslSubjectAlternativeNameIps=...

Example:

-Dmockserver.sslSubjectAlternativeNameIps="127.0.0.1,0.0.0.0"

Fixed (i.e. Custom) Inbound Private Key & X.509

File location of a fixed custom private key for TLS connections into MockServer.

The private key must be a PKCS#8 PEM file and must be the private key corresponding to the x509CertificatePath X.509 (public key) configuration.

The certificateAuthorityCertificate configuration must be the Certificate Authority for the corresponding X.509 certificate (i.e. able to valid its signature), see: x509CertificatePath.

To convert a PKCS#1 (i.e. default for Bouncy Castle) to a PKCS#8 the following command can be used: openssl pkcs8 -topk8 -inform PEM -in private_key_PKCS_1.pem -out private_key_PKCS_8.pem -nocrypt

This configuration will be ignored unless x509CertificatePath is also set.

Type: string Default: null

Java Code:

ConfigurationProperties.privateKeyPath(String privateKeyPath)

System Property:

-Dmockserver.privateKeyPath=...

Environment Variable:

MOCKSERVER_TLS_PRIVATE_KEY_PATH=...

Property File:

mockserver.privateKeyPath=...

Example:

-Dmockserver.privateKeyPath="/some/existing/path"

File location of a fixed custom X.509 Certificate for TLS connections into MockServer

The certificate must be a X.509 PEM file and must be the public key corresponding to the privateKeyPath private key configuration.

The certificateAuthorityCertificate configuration must be the Certificate Authority for this certificate (i.e. able to valid its signature).

This configuration will be ignored unless privateKeyPath is also set.

Type: string Default: null

Java Code:

ConfigurationProperties.x509CertificatePath(String x509CertificatePath)

System Property:

-Dmockserver.x509CertificatePath=...

Environment Variable:

MOCKSERVER_TLS_X509_CERTIFICATE_PATH=...

Property File:

mockserver.x509CertificatePath=...

Example:

-Dmockserver.x509CertificatePath="/some/existing/path"

Inbound mTLS Client Authentication (for Received Requests)

Require mTLS (also called client authentication and two-way TLS) for all TLS connections / HTTPS requests to MockServer

Type: boolean Default: false

Java Code:

ConfigurationProperties.tlsMutualAuthenticationRequired(boolean enable)

System Property:

-Dmockserver.tlsMutualAuthenticationRequired=...

Environment Variable:

MOCKSERVER_TLS_MUTUAL_AUTHENTICATION_REQUIRED=...

Property File:

mockserver.tlsMutualAuthenticationRequired=...

Example:

-Dmockserver.tlsMutualAuthenticationRequired="true"

File location of custom mTLS (TLS client authentication) X.509 Certificate Chain for Trusting (i.e. signature verification of) Client X.509 Certificates, the certificate chain must be a X.509 PEM file.

This certificate chain will be used if MockServer performs mTLS (client authentication) for inbound TLS connections because tlsMutualAuthenticationRequired is enabled

This configuration property is also used for MockServerClient to trust outbound TLS X.509 certificates i.e. TLS connections to MockServer

Type: string Default: null

Java Code:

ConfigurationProperties.tlsMutualAuthenticationCertificateChain(String certificateChain)

System Property:

-Dmockserver.tlsMutualAuthenticationCertificateChain=...

Environment Variable:

MOCKSERVER_TLS_MUTUAL_AUTHENTICATION_CERTIFICATE_CHAIN=...

Property File:

mockserver.tlsMutualAuthenticationCertificateChain=...

Example:

-Dmockserver.tlsMutualAuthenticationCertificateChain="/some/existing/path"


 

Outbound Client TLS/mTLS (for Forwarded or Proxied Requests)

Configure trusted set of certificates for forwarded or proxied requests (i.e. TLS connections out of MockServer).

MockServer will only be able to establish a TLS connection to endpoints that have a trusted X.509 certificate according to the trust manager type, as follows:

  • ANY - Insecure will trust all X.509 certificates and not perform host name verification.
  • JVM - Will trust all X.509 certificates trust by the JVM.
  • CUSTOM - Will trust all X.509 certificates specified in forwardProxyTLSCustomTrustX509Certificates configuration value.

Type: string Default: ANY

Java Code:

ConfigurationProperties.forwardProxyTLSX509CertificatesTrustManagerType(String trustManagerType)

System Property:

-Dmockserver.forwardProxyTLSX509CertificatesTrustManagerType=...

Environment Variable:

MOCKSERVER_FORWARD_PROXY_TLS_X509_CERTIFICATES_TRUST_MANAGER_TYPE=...

Property File:

mockserver.forwardProxyTLSX509CertificatesTrustManagerType=...

Example:

-Dmockserver.forwardProxyTLSX509CertificatesTrustManagerType="CUSTOM"

Fixed (i.e. Custom) Outbound CA X.509, Private Key & X.509

File location of custom file for trusted X.509 Certificate Authority roots for forwarded or proxied requests (i.e. TLS connections out of MockServer), the certificate chain must be a X.509 PEM file.

MockServer will only be able to establish a TLS connection to endpoints that have an X.509 certificate chain that is signed by one of the provided custom certificates, i.e. where a path can be established from the endpoints X.509 certificate to one or more of the custom X.509 certificates provided.

This configuration only take effect if forwardProxyTLSX509CertificatesTrustManagerType is configured as CUSTOM otherwise this value is ignored.

Type: string Default: null

Java Code:

ConfigurationProperties.forwardProxyTLSCustomTrustX509Certificates(String customX509Certificates)

System Property:

-Dmockserver.forwardProxyTLSCustomTrustX509Certificates=...

Environment Variable:

MOCKSERVER_FORWARD_PROXY_TLS_CUSTOM_TRUST_X509_CERTIFICATES=...

Property File:

mockserver.forwardProxyTLSCustomTrustX509Certificates=...

Example:

-Dmockserver.forwardProxyTLSCustomTrustX509Certificates="/some/existing/path"

File location of custom Private Key for forwarded or proxied requests (i.e. TLS connections out of MockServer), the private key must be a PKCS#8 PEM file

To convert a PKCS#1 (i.e. default for Bouncy Castle) to a PKCS#8 the following command can be used: openssl pkcs8 -topk8 -inform PEM -in private_key_PKCS_1.pem -out private_key_PKCS_8.pem -nocrypt

This private key will be used if MockServer needs to perform mTLS (client authentication) for outbound TLS connections.

Type: string Default: null

Java Code:

ConfigurationProperties.forwardProxyPrivateKey(String privateKey)

System Property:

-Dmockserver.forwardProxyPrivateKey=...

Environment Variable:

MOCKSERVER_FORWARD_PROXY_TLS_PRIVATE_KEY=...

Property File:

mockserver.forwardProxyPrivateKey=...

Example:

-Dmockserver.forwardProxyPrivateKey="/some/existing/path"

File location of custom X.509 Certificate Chain for forwarded or proxied requests (i.e. TLS connections out of MockServer), the certificates must be a X.509 PEM file

This certificate chain will be used if MockServer needs to perform mTLS (client authentication) for outbound TLS connections.

Type: string Default: null

Java Code:

ConfigurationProperties.forwardProxyCertificateChain(String certificateChain)

System Property:

-Dmockserver.forwardProxyCertificateChain=...

Environment Variable:

MOCKSERVER_FORWARD_PROXY_TLS_X509_CERTIFICATE_CHAIN=...

Property File:

mockserver.forwardProxyCertificateChain=...

Example:

-Dmockserver.forwardProxyCertificateChain="/some/existing/path"
 

MockServer Client

File location of custom mTLS (TLS client authentication) X.509 Certificate Chain for Trusting (i.e. signature verification of) MockServer X.509 Certificates, the certificate chain must be a X.509 PEM file. This certificate chain will only be used if MockServerClient performs TLS to calls to MockServer.

This settings is particularly used when connecting to MockServer via a load-balancer or other TLS terminating network infrastructure with its own X.509 Certificate.

This configuration property is also used for MockServer to trust inbound mTLS client authentication X.509 certificates

Type: string Default: null

Java Code:

ConfigurationProperties.tlsMutualAuthenticationCertificateChain(String certificateChain)

System Property:

-Dmockserver.tlsMutualAuthenticationCertificateChain=...

Environment Variable:

MOCKSERVER_TLS_MUTUAL_AUTHENTICATION_CERTIFICATE_CHAIN=...

Property File:

mockserver.tlsMutualAuthenticationCertificateChain=...

Example:

-Dmockserver.tlsMutualAuthenticationCertificateChain="/some/existing/path"
 

Bouncy Castle

Use BouncyCastle instead of the Java JDK to X.509 Certificate creation, this is helpful if:

  • using Java 16+ or
  • using the IBM JVM or
  • avoiding bugs in the X509 creation logic Java JDK (i.e. such as the format of SAN and CN)

When enabling this setting the following dependencies must be provided on the classpath (they are not included with MockServer)

<dependency>
  <groupId>org.bouncycastle</groupId>
  <artifactId>bcprov-jdk15on</artifactId>
  <version>1.70</version>
</dependency>
<dependency>
  <groupId>org.bouncycastle</groupId>
  <artifactId>bcpkix-jdk15on</artifactId>
  <version>1.70</version>
</dependency>

Type: boolean Default: false

Java Code:

ConfigurationProperties.useBouncyCastleForKeyAndCertificateGeneration(boolean enable)

System Property:

-Dmockserver.useBouncyCastleForKeyAndCertificateGeneration=...

Environment Variable:

MOCKSERVER_USE_BOUNCY_CASTLE_FOR_KEY_AND_CERTIFICATE_GENERATION=...

Property File:

mockserver.useBouncyCastleForKeyAndCertificateGeneration=...

Example:

-Dmockserver.useBouncyCastleForKeyAndCertificateGeneration="true"
 

Logging & Metrics Configuration:

The the minimum level of logs to record in the event log and to output to system out (if system out log output is not disabled). The lower the log level the more log entries will be captured, particularly at TRACE level logging.

Type: string Default: INFO

Java Code:

ConfigurationProperties.logLevel(String level)

System Property:

-Dmockserver.logLevel=...

Environment Variable:

MOCKSERVER_LOG_LEVEL=...

Property File:

mockserver.logLevel

The log level, which can be TRACE, DEBUG, INFO, WARN, ERROR, OFF, FINEST, FINE, INFO, WARNING, SEVERE

Example:

-Dmockserver.logLevel="DEBUG"

Disable logging to the system output

Type: boolean Default: false

Java Code:

ConfigurationProperties.disableSystemOut(boolean disableSystemOut)

System Property:

-Dmockserver.disableSystemOut=...

Environment Variable:

MOCKSERVER_DISABLE_SYSTEM_OUT=...

Property File:

mockserver.disableSystemOut=...

Example:

-Dmockserver.disableSystemOut="true"

Disable all logging and processing of log events

Type: boolean Default: false

Java Code:

ConfigurationProperties.disableLogging(boolean disableLogging)

System Property:

-Dmockserver.disableLogging=...

Environment Variable:

MOCKSERVER_DISABLE_LOGGING=...

Property File:

mockserver.disableLogging=...

Example:

-Dmockserver.disableLogging="true"

Enable the recording of metrics for different activities within MockServer, such as, EXPECTATION_NOT_MATCHED_COUNT, ACTION_RESPONSE_COUNT, WEBSOCKET_CALLBACK_CLIENT_COUNT, etc

Type: boolean Default: false

Java Code:

ConfigurationProperties.metricsEnabled(boolean enable)

System Property:

-Dmockserver.metricsEnabled=...

Environment Variable:

MOCKSERVER_METRICS_ENABLED=...

Property File:

mockserver.metricsEnabled=...

Example:

-Dmockserver.metricsEnabled="true"
 

Proxying Configuration:

If true (the default) when no matching expectation is found, and the host header of the request does not match MockServer's host, then MockServer attempts to proxy the request if that fails then a 404 is returned.

If false when no matching expectation is found, and MockServer is not being used as a proxy, then MockServer always returns a 404 immediately.

Type: string Default: true

Java Code:

ConfigurationProperties.attemptToProxyIfNoMatchingExpectation(boolean enable)

System Property:

-Dmockserver.attemptToProxyIfNoMatchingExpectation=...

Environment Variable:

MOCKSERVER_ATTEMPT_TO_PROXY_IF_NO_MATCHING_EXPECTATION=...

Property File:

mockserver.attemptToProxyIfNoMatchingExpectation=...

Example:

-Dmockserver.attemptToProxyIfNoMatchingExpectation="false"

Use HTTP proxy (i.e. via Host header) for all outbound / forwarded requests

Type: string Default: null

Java Code:

ConfigurationProperties.forwardHttpProxy(String hostAndPort)

System Property:

-Dmockserver.forwardHttpProxy=...

Environment Variable:

MOCKSERVER_FORWARD_HTTP_PROXY=...

Property File:

mockserver.forwardHttpProxy=...

Example:

-Dmockserver.forwardHttpProxy="127.0.0.1:1090"

Use HTTPS proxy (i.e. HTTP CONNECT) for all outbound / forwarded requests, supports TLS tunnelling of HTTPS requests

Type: string Default: null

Java Code:

ConfigurationProperties.forwardHttpsProxy(String hostAndPort)

System Property:

-Dmockserver.forwardHttpsProxy=...

Environment Variable:

MOCKSERVER_FORWARD_HTTPS_PROXY=...

Property File:

mockserver.forwardHttpsProxy=...

Example:

-Dmockserver.forwardHttpsProxy="127.0.0.1:1090"

Use SOCKS proxy for all outbound / forwarded requests, support TLS tunnelling of TCP connections

Type: string Default: null

Java Code:

ConfigurationProperties.forwardSocksProxy(String hostAndPort)

System Property:

-Dmockserver.forwardSocksProxy=...

Environment Variable:

MOCKSERVER_FORWARD_SOCKS_PROXY=...

Property File:

mockserver.forwardSocksProxy=...

Example:

-Dmockserver.forwardSocksProxy="127.0.0.1:1090"

Username for proxy authentication when using HTTPS proxy (i.e. HTTP CONNECT) for all outbound / forwarded requests

Note: 8u111 Update Release Notes state that the Basic authentication scheme has been deactivated when setting up an HTTPS tunnel. To resolve this clear or set to an empty string the following system properties: jdk.http.auth.tunneling.disabledSchemes and jdk.http.auth.proxying.disabledSchemes.

Type: string Default: null

Java Code:

ConfigurationProperties.forwardProxyAuthenticationUsername(String forwardProxyAuthenticationUsername)

System Property:

-Dmockserver.forwardProxyAuthenticationUsername=...

Environment Variable:

MOCKSERVER_FORWARD_PROXY_AUTHENTICATION_USERNAME=...

Property File:

mockserver.forwardProxyAuthenticationUsername=...

Example:

-Dmockserver.forwardProxyAuthenticationUsername=john.doe

Password for proxy authentication when using HTTPS proxy (i.e. HTTP CONNECT) for all outbound / forwarded requests

Note: 8u111 Update Release Notes state that the Basic authentication scheme has been deactivated when setting up an HTTPS tunnel. To resolve this clear or set to an empty string the following system properties: jdk.http.auth.tunneling.disabledSchemes and jdk.http.auth.proxying.disabledSchemes.

Type: string Default: null

Java Code:

ConfigurationProperties.forwardProxyAuthenticationPassword(String forwardProxyAuthenticationPassword)

System Property:

-Dmockserver.forwardProxyAuthenticationPassword=...

Environment Variable:

MOCKSERVER_FORWARD_PROXY_AUTHENTICATION_PASSWORD=...

Property File:

mockserver.forwardProxyAuthenticationPassword=...

Example:

-Dmockserver.forwardProxyAuthenticationPassword="p@ssw0rd"

The authentication realm for proxy authentication to MockServer

Type: string Default: MockServer HTTP Proxy

Java Code:

ConfigurationProperties.proxyAuthenticationRealm(String proxyAuthenticationRealm)

System Property:

-Dmockserver.proxyAuthenticationRealm=...

Environment Variable:

MOCKSERVER_PROXY_SERVER_REALM=...

Property File:

mockserver.proxyAuthenticationRealm=...

Example:

-Dmockserver.proxyAuthenticationRealm="MockServer HTTP Proxy"

The required username for proxy authentication to MockServer

Note: 8u111 Update Release Notes state that the Basic authentication scheme has been deactivated when setting up an HTTPS tunnel. To resolve this clear or set to an empty string the following system properties: jdk.http.auth.tunneling.disabledSchemes and jdk.http.auth.proxying.disabledSchemes.

Type: string Default: john.doe

Java Code:

ConfigurationProperties.proxyAuthenticationUsername(String proxyAuthenticationUsername)

System Property:

-Dmockserver.proxyAuthenticationUsername=...

Environment Variable:

MOCKSERVER_PROXY_AUTHENTICATION_USERNAME=...

Property File:

mockserver.proxyAuthenticationUsername=...

Example:

-Dmockserver.proxyAuthenticationUsername=john.doe

The required password for proxy authentication to MockServer

Note: 8u111 Update Release Notes state that the Basic authentication scheme has been deactivated when setting up an HTTPS tunnel. To resolve this clear or set to an empty string the following system properties: jdk.http.auth.tunneling.disabledSchemes and jdk.http.auth.proxying.disabledSchemes.

Type: string Default: p@ssw0rd

Java Code:

ConfigurationProperties.proxyAuthenticationPassword(String proxyAuthenticationPassword)

System Property:

-Dmockserver.proxyAuthenticationPassword=...

Environment Variable:

MOCKSERVER_PROXY_AUTHENTICATION_PASSWORD=...

Property File:

mockserver.proxyAuthenticationPassword=...

Example:

-Dmockserver.proxyAuthenticationPassword="p@ssw0rd"
 

Initialization & Persistence Configuration:

The class (and package) used to initialize expectations in MockServer at startup, if set MockServer will load and call this class to initialise expectations when is starts.

Type: string Default: null

Java Code:

ConfigurationProperties.initializationClass(String initializationClass)

System Property:

-Dmockserver.initializationClass=...

Environment Variable:

MOCKSERVER_INITIALIZATION_CLASS=...

Property File:

mockserver.initializationClass=...

Example:

-Dmockserver.initializationClass="org.mockserver.server.initialize.ExpectationInitializerExample"

The path to the json file used to initialize expectations in MockServer at startup, if set MockServer will load this file and initialise expectations for each item in the file when is starts.

The expected format of the file is a JSON array of expectations, as per the REST API format

Type: string Default: null

Java Code:

ConfigurationProperties.initializationJsonPath(String initializationJsonPath)

System Property:

-Dmockserver.initializationJsonPath=...

Environment Variable:

MOCKSERVER_INITIALIZATION_JSON_PATH=...

Property File:

mockserver.initializationJsonPath=...

Example:

-Dmockserver.initializationJsonPath=org/mockserver/server/initialize/initializerJson.json

If enabled the initialization json file will be watched for changes, any changes found will result in expectations being created, remove or updated by matching against their key.

If duplicate keys exist only the last duplicate key in the file will be processed and all duplicates except the last duplicate will be removed.

The order of expectations in the file is the order in which they are created if they are new, however, re-ordering existing expectations does not change the order they are matched against incoming requests.

Type: boolean Default: false

Java Code:

ConfigurationProperties.watchInitializationJson(boolean enable)

System Property:

-Dmockserver.watchInitializationJson=...

Environment Variable:

MOCKSERVER_WATCH_INITIALIZATION_JSON=...

Property File:

mockserver.watchInitializationJson=...

Example:

-Dmockserver.watchInitializationJson="org/mockserver/server/initialize/initializerJson.json"

Enable the persisting of expectations as json, which is updated whenever the expectation state is updated (i.e. add, clear, expires, etc)

Type: boolean Default: false

Java Code:

ConfigurationProperties.persistExpectations(boolean persistExpectations)

System Property:

-Dmockserver.persistExpectations=...

Environment Variable:

MOCKSERVER_PERSIST_EXPECTATIONS=...

Property File:

mockserver.persistExpectations=...

Example:

-Dmockserver.persistExpectations="true"

The file path used to save persisted expectations as json, which is updated whenever the expectation state is updated (i.e. add, clear, expires, etc)

Type: string Default: persistedExpectations.json

Java Code:

ConfigurationProperties.persistedExpectationsPath(String persistedExpectationsPath)

System Property:

-Dmockserver.persistedExpectationsPath=...

Environment Variable:

MOCKSERVER_PERSISTED_EXPECTATIONS_PATH=...

Property File:

mockserver.persistedExpectationsPath=...

Example:

-Dmockserver.persistedExpectationsPath="org/mockserver/server/initialize/initializerJson.json"
 

CORS Configuration:

Enabled CORS for MockServer REST API so that the API can be used from javascript running in browsers, such as selenium

Type: boolean Default: true

Java Code:

ConfigurationProperties.enableCORSForAPI(boolean enableCORSForAPI)

System Property:

-Dmockserver.enableCORSForAPI=...

Environment Variable:

MOCKSERVER_ENABLE_CORS_FOR_API=...

Property File:

mockserver.enableCORSForAPI=...

Example:

-Dmockserver.enableCORSForAPI="false"

Enabled CORS for all responses from MockServer, including the REST API and expectation responses

Type: boolean Default: false

Java Code:

ConfigurationProperties.enableCORSForAllResponses(boolean enableCORSForAllResponses)

System Property:

-Dmockserver.enableCORSForAllResponses=...

Environment Variable:

MOCKSERVER_ENABLE_CORS_FOR_ALL_RESPONSES=...

Property File:

mockserver.enableCORSForAllResponses=...

Example:

-Dmockserver.enableCORSForAllResponses="true"

Configure the default value used for CORS in the access-control-allow-headers and access-control-expose-headers headers.

In addition to this default value any headers specified in the request header access-control-request-headers also get added to access-control-allow-headers and access-control-expose-headers headers in a CORS response.

Type: string Default: Allow, Content-Encoding, Content-Length, Content-Type, ETag, Expires, Last-Modified, Location, Server, Vary, Authorization

Java Code:

ConfigurationProperties.corsAllowHeaders(String corsAllowHeaders)

System Property:

-Dmockserver.corsAllowHeaders=...

Environment Variable:

MOCKSERVER_CORS_ALLOW_HEADERS=...

Property File:

mockserver.corsAllowHeaders=...

Example:

-Dmockserver.corsAllowHeaders="Allow, Content-Encoding, Content-Length, Content-Type, ETag, Expires, Last-Modified, Location, Server, Vary, Authorization"

Configure the value used for CORS in the access-control-allow-methods header.

Type: string Default: CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT, PATCH, TRACE

Java Code:

ConfigurationProperties.corsAllowMethods(String corsAllowMethods)

System Property:

-Dmockserver.corsAllowMethods=...

Environment Variable:

MOCKSERVER_CORS_ALLOW_METHODS=...

Property File:

mockserver.corsAllowMethods=...

Example:

-Dmockserver.corsAllowMethods="CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT, PATCH, TRACE"

Configure the value used for CORS in the access-control-allow-credentials header.

Type: boolean Default: true

Java Code:

ConfigurationProperties.corsAllowCredentials(boolean allow)

System Property:

-Dmockserver.corsAllowCredentials=...

Environment Variable:

MOCKSERVER_CORS_ALLOW_CREDENTIALS=...

Property File:

mockserver.corsAllowCredentials=...

Example:

-Dmockserver.corsAllowCredentials=false

Configure the value used for CORS in the access-control-max-age header.

Type: int Default: 300

Java Code:

ConfigurationProperties.corsMaxAgeInSeconds(int maxAgeInSeconds)

System Property:

-Dmockserver.corsMaxAgeInSeconds=...

Environment Variable:

MOCKSERVER_CORS_MAX_AGE_IN_SECONDS=...

Property File:

mockserver.corsMaxAgeInSeconds=...

Example:

-Dmockserver.corsMaxAgeInSeconds=100