This topic explains how to configure deployment settings for Virtualize servers. Refer to Configuring Virtual Assets Deployed to Virtualize Server for details on configuring individual virtual asset deployment settings deployed to a server. 

In this section:

Configuring Virtualize Server Startup and Authentication Options

You can configure additional settings (for example, startup, authentication, and CTP notification options) from the Preferences panel as described in Server Settings.

Security Considerations

You should deploy the Virtualize server in a secure manner on a trusted network. The Virtualize server hosts web services that can be used to manage virtual assets, so any host with network access to the Virtualize server can add, modify, or remove virtual assets hosted by that Virtualize server. You could use a proxy server or gateway in front of the Virtualize server to apply additional layers of security other than what is provided by the Virtualize server.

The Virtualize server's HTTPS port (9443) should be used when sending login credentials. 

Take extra caution when deploying a Virtualize server on an untrusted network, such as the Internet. We recommend that you use a firewall to block unacceptable access (such as restricting access by IP addresses). A proxy server or gateway could also be used in front of the Virtualize server to add authentication, filtering, and logging.

Configuring SSL (HTTPS) for the Virtualize Server

If the AUT is deployed to an environment that communicates over SSL, you will need to make sure that the Virtualize server can communicate with the AUT and its dependencies. There are several options:

1. (Preferred) Create a certificate for the Virtualize server, sign it with a certificate authority that is trusted by the AUT, and issue it for the host where the Virtualize server is installed. With this option, you don’t need to make any changes to the AUT.
2. Configure Virtualize Server with a generated (possibly self-signed) certificate and add it to the trust store of the AUT.
3. Add your actual server certificate to Virtualize. This option assumes that access to the server certificate and keys is possible—and changes to the AUT are difficult or should be avoided. However, this option may not be possible if the certificate was signed for a hostname other than the hostname where Virtualize is deployed.
4. Disable certificate trust in the AUT. The AUT would still connect over SSL but trust any server (such as the Virtualize server) without validating its certificate or its trust paths.

For the AUT to accept a certificate/private key pair, you generally need—at minimum—a self-signed certificate/private key pair whose common name (CN) parameter matches the fully-qualified name of the server. For example, if your Virtualize server URL is http://myserver.mycompany.com, the CN parameter should be "myserver.mycompany.com".

In any case, Virtualize can be configured to accept incoming HTTPS connections on port 9443 (default SSL connector) or another port. 

Configuring server.xml

SSL details can be configured by modifying the SSL HTTP/1.1 Connector entry in server.xml. For example:

<Connector port="9443" maxHttpHeaderSize="8192"
maxThreads="150" minSpareThreads="25" maxSpareThreads="75" enableLookups="false" disableUploadTimeout="true"
acceptCount="100" scheme="https" secure="true"
clientAuth="false" sslProtocol="TLS"
keystoreFile="C:/Path To Keystore/virtualize.pfx"
keystorePass="security" keyAlias="virtualize" keystoreType="PKCS12" truststoreFile="../lib/cacerts"
truststorePass="changeit" truststoreType="JKS" />

To access the server.xml file, launch Virtualize and ensure that at least one responder has been created. The file is located in the <INSTALL>/plugins/com.parasoft.ptest.libs.web_<version>/root/tomcat/conf directory.

keystoreFile

The value you set for the keystoreFile attribute in server.xml depends on your configuration option. 

If you use the preferred option (option 1) or option 2, use the path to the generated server keystore. Although the keystore paths can be relative to the location of the server.xml file, it is best to provide absolute paths in order to ensure correct configuration. 

If you use option 3, the attribute should point to the same keystore file as the actual SSL-based service that you want to emulate. Use forward slashes (/) instead of backward slashes (\).For example, C:/Users/myUser/keystore.jks.

With option 4, you do not need to modify the keystoreFile attribute.

keystorePass

Set the keystorePass attribute to be the password to your keystore.

keyAlias

Set the keyAlias attribute to point to the alias of the certificate/private key pair

keystoreType

Set the keystoreType to the type of keystore you are using, such as PKCS12, JKS, BKS, UBER, or PEM.

clientAuth

For two-way SSL (mutual authentication), the clientAuth attribute must be set to true and the trust store used for validating client certificates should be specified using the truststoreFile, truststorePass, and truststoreType attributes:

• Modify truststoreFile to point to your keystore file. Use forward slashes (/) instead of backward slashes (\). For example, C:/Users/myUser/keystore.jks
• Modify truststorePass to be the password to your keystore
• Modify truststoreType to PKCS12, JKS, BKS, UBER, or PEM—depending on the type of keystore you're using.

Additional Configuration Details

For more details on how to enable and configure the SSL connector, see the Apache Tomcat documentation (https://tomcat.apache.org/tomcat-8.5-doc/ssl-howto.html).

It is possible to configure more than one port number for SSL. This is typically the case if different keystore/certificate configurations need to be virtualized.

The default SSL connector (the one with attribute name="default") port number should be changed in the Virtualize server preferences (see Server Settings for details). When Virtualize starts, the preferences settings will take precedence over the server.xml settings.

You may add additional Connector elements to server.xml with distinct names and distinct SSL/certificate configurations as needed. Virtual assets and proxies cannot be mapped to specific Connector ports. A message received on a particular connector/port could be processed by any virtual asset based on header, URL and message content correlation criteria within the virtual asset path, proxy path or responder correlation rules, but not based on the port.

URI Character Encoding

The Virtualize server supports Tomcat's relaxedPathChars and relaxedQueryChars properties (see https://tomcat.apache.org/tomcat-8.5-doc/config/http.html). These properties enable you to specify which unencoded characters should be allowed in URI paths and URI query strings. You can specify the following characters: " < > [ \ ] ^ ` { | }

If you do not specify which characters are allowed, the Tomcat server will reject messages that contain one or more of the unencoded characters in URI paths and queries. 

Add the relaxedPathChars and relaxedQueryChars attributes to the <Connector> element in the server.xml file and specify the characters you want to allow. If there is more than one <Connector> element, add the attributes to the elements with the protocol set to HTTP and HTTPS. The file is located in the <INSTALL>/plugins/com.parasoft.ptest.libs.web_<version>/root/tomcat/conf directory.

Example:

<Connector
   URIEncoding="UTF-8" allowTrace="true" connectionTimeout="20000"
   enableLookups="true" name="default" port="9080" protocol="HTTP/1.1"
   redirectPort="9443" 
   server="Parasoft Server"
   relaxedPathChars="&quot; &lt; &gt; [ \ ] ^ ` { | }"
   relaxedQueryChars="&quot; &lt; &gt; [ \ ] ^ ` { | }"
/>

You can also configure these properties at the HTTP Listener level. See HTTP Configuration.

Accessing the Server Configuration Panel

You can configure various preferences and settings for a Virtualize server in the server configuration panel. To open this panel:

1. Start Virtualize Server in GUI mode.
2. In the Virtualize Server view, double-click on the server node to open the configuration panel.
    

From this panel, you can review and modify settings related to monitoring, server statistics, global JMS and MQ connections, and user authentication (for remote servers only). 

Monitoring Tab

This tab displays a summary of Virtualize server statistics. See Collecting Server Statistics for details.

Server Configuration Tab

Click the Server Configuration tab to view and configure event monitoring and statistics collection settings. See the following chapters for information about the settings in this tab: 

• Gaining Visibility into Server Events 
• Collecting Server Statistics 

Connections Tab

If the application under test sends and receives messages through an MQ Queue Manager or JMS provider, click the Connections to define connection settings. Assets and proxies deployed to the Virtualize server can be configured to use the connection settings to communicate with the application under test. You can perform the following actions:

• add a new connection (see Adding MQ Queue Manager Connections)
• remove a connection 
• modify a connection
• copy the connection configuration from an existing connection to another server (see Copying an MQ Manager Connection)

Adding MQ Queue Manager Connections

Click Add in the MQ Queue Managers section and specify the following configurations. Click Test Connections after configuration to verify proxies and virtual assets on the server will be able to communicate with the Queue Manager. The settings configured in this interface are also used in the virtual asset or proxy configuration panels. 

Mode

Choose one of the following modes from the drop-down menu:

• Default - allows you to manually enter connection details, such as host, port, and channel
• CCDT - allows you to specify a client channel definition table (CCDT) file that provides connection details
• Bindings - use Bindings mode when the queue manager and connected applications are running on the same system. The IBM WebSphere MQ Java API connects directly to the queue manager using the Java Native Interface (JNI). To use the bindings transport, the IBM MQ classes for JMS must be run in an environment that has access to the IBM MQ Java Native Interface libraries.

Host (Default Mode)

Specify the MQ queue manager host.

Port (Default Mode)

Specify MQ queue manager port.

Channel (Default Mode)

Specify MQ queue manager channel.

CCDT File (CCDT Mode)

Specify the location of the client channel definition table file, which provides connection details.

Queue manager

Specify the name of the queue manager.

Username

If login credentials are required, specify the user name in this field.

Password

If login credentials are required, specify the password in this field.

SSL Properties

Enable the Use SSL when connecting to the service option and configure the SSL settings if the virtual assets and message proxies hosted on the Virtualize Server are required to communicate with the service under test over SSL. 

Enable the Trust all server certificates option to allow Virtualize Server to accept any certificate. This option disables trust validation when virtual assets or message proxies on the server establish connections with services and forces assets or proxies to accept connections using any certificates services present. In general, this option should be enabled if certificate trust is not a focus for the environment where Virtualize is deployed.

CipherSuite (SSL)

Specifies the CipherSuite to use for the SSL connection on the specified MQ Channel. Refer to the IBM MQ documentation to determine which CipherSuite to select based on the CipherSpec. 

Peer Name (SSL)

(Optional) Specifies a peer name to verify that the certificate presented by the Queue Manager matches the criteria specified with the peer name parameter. A server certificate will match this parameter with the Distinguished Name (DN) of the certificate presented by the Queue Manager. 

Keystore Settings

Specify the key store file, key store password, and key store type to be used by the queue manager to authenticate virtual assets and message proxies over SSL.  If the MQ Channel does not require SSL, then the key store settings are not required. After configuring the key store settings, click Validate to verify that the settings are configured correctly. 

Trust Store Settings

Specify the file, password, and store type to be used by the virtual assets to authenticate the Queue Manager over SSL. After configuring the trust store settings, click Validate to verify that the settings are configured correctly.

Enabling the Trust all server certificates option disables the trust store configuration settings.

If using key/trust stores, you will need to download and install the Unlimited Strength Java Cryptography Extension. For details, see JCE Prerequisite.

Copying an MQ Manager Connection

You can copy existing MQ manager connection settings between servers. You can copy settings from a remote server or the local server.

1. Open the server settings that contains the connection configuration you want to copy. For example, if you want to copy the connection settings from a remote server to your local instance, open the remote server's configuration panel.
2. Click the Connections tab and choose the connection configurations you want to copy. You can copy a single connection or multiple connections by pressing and holding the CTRL or COMMAND key.
3. Click Copy and specify destination server for the connection settings from the drop-down menu.
4. Click OK to copy the settings. Settings will not be copied if they already exist on the destination server. 

Using MQ Queue Manager Connection Settings

After you add a connection, you will be able to choose it from the configuration panel as you add and configure proxies and virtual assets hosted on Virtualize Server. For example, this shows how to select a global connection for a proxy using MQ:

Adding JMS Connections

Click Add in the JMS Connection settings section and specify the JMS configurations. See JMS Provider Configuration for details on configuring JMS connection settings.

Click Test Connections after configuration to verify proxies and virtual assets on the server will be able to communicate with the JMS provider. The settings configured in this interface are also used in the virtual asset or proxy configuration panels.

Using JMS Connection Settings

After you add a connection, you will be able to choose it from the configuration panel as you add and configure proxies and virtual assets hosted on Virtualize Server. 

For example, this shows how to select a global connection for a virtual asset using JMS:

Using an Alternative Port for the Virtualize HTTP Server

By default, the local Virtualize server uses port 9080. To change this:

1. Choose Parasoft> Preferences.
2. Open Parasoft> Server.
3. Change the port settings.
4. Restart the server.