Configuring QuerySurge with HTTPS – Customer Support

Versions:6.1+

QuerySurge Data Security on the Wire: HTTPS/SSL

By default, communications between QuerySurge components (the QuerySurge App Server, the browser, the QuerySurge Agents and QuerySurge Statsmon) are conducted in the HTTP protocol. This means that, on the wire, these communications are not encrypted. Since QuerySurge is typically deployed behind the organization's firewall, this has generally been considered to be safe.

Some organizations need a higher level of data security, however, and the Web has a ready-made option: deployment under HTTPS/SSL. This is a standard option that means that all wire transmissions are encrypted, and are decrypted when they arrive. As a Web 2.0 app, QuerySurge can be deployed under HTTPS/SSL.

The deployment tasks involve reconfiguring your QuerySurgeTomcat instance to use HTTPS/SSL, and configuring all of the connecting QuerySurge components to use HTTPS/SSL. These components include your QuerySurge Agents, and QuerySurge Statsmon (which monitors your database). Your browsers minimally will need URLs modified for https://

Preliminary Task - Obtain a Certificate

In order to deploy with HTTPS/SSL, you will need to obtain a Certificate ("cert") and/or keystore (cert and private key merged) from a Certificate Authority (CA) that is issued specifically to your organization by the CA. It is likely that there is already a mechanism in your organization to request a Certificate or keystore. In addition, you may need to work with an admin in your organization to obtain and deploy the cert or keystore, as organizations may have specific procedures for this. The cert or keystore-containing file can have one of a number of file formats/extensions, including: ".crt", ".der", ".pfx", ".jks", ".pem". ".p7b". "p12"

Note: The CSR (Certificate Signing Request) required to obtain the cert for your QuerySurge App Server must be generated under carefully prepared circumstances. Check with your internal security organization for details. Typically, either the CSR must be generated from the keystore of your QuerySurge App Server (if needed, work with a network or security admin from your organization to start the process of obtaining a cert for your App Server) or it may be generated from an external tool provided by your organization. In this latter case, you'll likely need to manually merge your private key with your certificate into a new keystore using a tool like OpenSSL. You may need to work with a network or security admin from your organization to arrange this.

Note: The instructions below use the default truststore for the Java that QuerySurge distributes with.

Note: With QuerySurge versions 12.0 and higher, your SSL certificate must contain at least one Subject Alternative Name (SAN). This SAN will be used to verify the server by all clients (browser, Agent, Statsmon, etc.). If not present, the client may not be able to connect successfully to the server.

QuerySurge Configuration Tasks

1. Take your QuerySurge Services Down

Once you have completed the preliminary tasks (obtained a cert, and have the proper rights to proceed), you'll need to take your QuerySurge services down. This means the QuerySurge App Server, your QuerySurge Agents, and QuerySurge Statsmon on your database server. Take the services down in the following order:

QuerySurge Agent(s)
QuerySurge Statsmon
QuerySurgeTomcat
QuerySurgeMySQL (optional shutdown)

2. Import your CERT or Key Pair to the QuerySurge App Server Truststore

If your CSR was generated using the default Java truststore (cacerts), only the certificate (and possibly the certificate chain) need to be imported. Locate your certificate file and copy it to: /<QuerySurge Install Dir>/QuerySurge/java/lib/security/. Then use the keytool to import the file into the default Java truststore (cacerts), using the following command:

keytool -import -alias <your alias> -file <your certificate file> -keystore cacerts

If your CSR was generated external to the default cacerts Java truststore, the new keystore (PKCS12 format) needs to be imported. Locate the new keystore and copy it to the /<QuerySurge Install Dir>/QuerySurge/java/lib/security/ directory. Then use the keytool to import the file into the default Java truststore (cacerts), using the following command:

keytool -v -importkeystore -srckeystore <path to your pfx file> -srcstoretype PKCS12 -destkeystore cacerts -deststoretype JKS -srcalias <alias from the PFX file> -destalias <new alias in the QS cacerts>

The 'alias' is an alias to this entry in the truststore. The 'file' is the cert file that has been obtained for the QuerySurge App Server.

Note: It is important to know the alias of the certificate that was generated for your QuerySurge server as you will want to use the same alias when importing it into the cacerts truststore.

Note: If prompted for a password while importing the cert, the default password for the cacerts truststore is: "changeit". If you want to change it, you can find instructions here.

EXAMPLE 2.1 (Windows 64-Bit Install)

Note: You may need to use the fully qualified path to access the keytool or truststore based on how and where you are calling this command. In the example above, we navigate to QuerySurge's truststore directory and call the keytool using the fully qualified path name. This applies to the keytool commands in the later steps as well.

Note: If you encounter an error message like "Input not an X.509 certificate" you may have to have the certificate regenerated in a more Java-friendly encoding like ".der".

Note: If your certificate requires a password, upon import you may encounter an error message like "Cannot recover key". This means that the password for the certificate is different than the password of your cacerts truststore. You will have to update the password for the cacerts truststore to the same password as the certificate. Again, you can find instructions on how to change truststore password here.

3. Configure QuerySurgeTomcat to Use HTTPS/SSL

Navigate to the /<QuerySurge Install Dir>/QuerySurge/tomcat/conf/ directory and open the server.xml file. Modify this file to enable HTTPS and disable HTTP.

Uncomment the SSL Connector tag and modify the protocol attribute as below; add attributes for the keystoreFile and keystorePass, as shown below:

<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol" SSLEnabled="true"
maxThreads="150" scheme="https" secure="true" keystoreFile="<QuerySurge Install Dir>\QuerySurge\java\lib\security\cacerts" keystorePass="<keystore-password>" clientAuth="false" sslProtocol="TLS" />

Note: The keyStoreFile path shown above uses a template for the QuerySurge install directory at the beginning of the path. You'll need to replace this with the actual path on your QuerySurge App server.

Note: If the following child tag is defined within the new tag for SSL connections, remove it:

<SSLHostConfig><Certificate certificateKeystoreFile="conf/localhost-rsa.jks" type="RSA" /></SSLHostConfig>

Note: The default value for the "protocol" attribute will need to be updated from protocol="HTTP/1.1" to protocol="org.apache.coyote.http11.Http11NioProtocol" if not already done.

Note: If you have installed QuerySurge on Windows, the 8.3 "short" path naming convention may or may not be acceptable for the keyStoreFile path, depending on the OS configuration. Issues with the path are most likely to occur if your QuerySurge installation is not on your C:\ drive.

Note: The default Apache port for HTTPS is 8443. You may need to change this to conform to organizational standards.

Lastly, comment out the HTTP Connector tag, so that port 80 (or whatever HTTP port is in use) is closed, so that the QuerySurge App server listens only on the HTTPS port:

4. Export your CERT from the QuerySurge App Server Truststore and Import into Agent, Statsmon, QuerySurge APIs and Test Management Connector (for HP ALM/QC, IBM RQM and MS TFS integrations) Truststores

For multi-machine installations where multiple QuerySurge Agent(s), multiple API(s) and Test Management Connector API machines and the QuerySurge Statsmon service are running on different machines, you'll need to export a cert and import it on each Agent machine, the API(s) and Test Management Connector API machines and on the Statsmon deployment (on the QuerySurge Database machine).

Run the following command on the App Server (i.e., the box on which the previous steps (2) - (3) have already been executed). You only need to do this once:

keytool -export -alias <your alias> -rfc -file qscert.crt -keystore cacerts

EXAMPLE 4.1 (Windows 64-Bit Install)

Copy the cert file produced from the above command to all Agent machines, all API and Test Management Connector machines and to the Statsmon machine (again, this is the QuerySurge Database machine). On the Agent, API installations and Test Management Connector API and/or Statsmon (i.e., database) installations, run the following command:

keytool -import -alias <your alias> -file qscert.crt -keystore cacerts

EXAMPLE 4.2 (Windows 64-Bit Install)

5. Modify the Agent Configuration

For each Agent machine you've configured for SSL/HTTPS, you'll need to modify the URL to reflect the protocol change to HTTPS from HTTP.

If your Agent is on Windows, the open the Agent Service Console (you may need elevated or Admin rights to do this). In the QuerySurge Server box, double-click on http:// to toggle from http to https. In addition, you may need to add or change the port to the HTTPS port.

If your Agent is on Linux, you will have to modify the agentconfig.xml file.

You can find the agentconfig.xml file at:
/<QuerySurge Install Dir>/QuerySurge/agent/config/. In the default install, this path is: /opt/QuerySurge/agent/config/.

Make a copy of this file:
[sudo] cp agentconfig.xml agentconfig.xml.orig
Carefully edit the file with a text editor to modify the <qsserverurl> tag for HTTPS:
<qsserverurl>https://server-name:https-port/QuerySurge/services/QuerySurge</qsserverurl>
Save the file

6. Modify the Statsmon Configuration File

For the Statsmon machine, you'll need to modify the statsmonconfig.xml file to reflect the protocol change (to HTTPS from HTTP) and port change (to your HTTPS port from your HTTP port), as shown below.

You can find the statsmonconfig.xml file at:
\\<QuerySurge Install Dir>\QuerySurge\statsmon\config\. In the default install (Windows), this path is:
C:\Program Files\QuerySurge\statsmon\config\. On Linux, the default path is: /opt/QuerySurge/statsmon/config/.

Make a copy of this file:
[sudo] cp statsmonconfig.xml statsmonconfig.xml.orig
Carefully edit the file with a text editor to modify the <qsserverurl> tag for HTTPS:
<qsserverurl>https://server-name:https-port</qsserverurl>
Save the file

7. Modify the API Properties File

For each API installation or Test Management Connector API installation you've configured for SSL/HTTPS, you'll need to modify the qsapi.properties file to reflect the protocol change to HTTPS from HTTP.

You can find the qsapi.properties file at:
\\<QuerySurge Install Dir>\QuerySurge\cli\. In the default install (Windows), this path is:
C:\Program Files\QuerySurge\cli\. On Linux, the default path is: /opt/QuerySurge/cli/.

Make a copy of this file.
Note: On the Linux command line, use:
[sudo] cp qsapi.properties qsapi.properties.orig
Carefully edit the file with a text editor to add the following entry: protocol=https
Save the file

Note: In many cases, your QuerySurge URL(s) will reside either in a script (batch [Windows], bash [Linux] or VBS), and you will need to modify any URLs for HTTPS.

8. Re-start your QuerySurge Services

Start the services in the reverse of the order you stopped them in:

QuerySurgeMySQL (if shutdown, restart this first)
QuerySurgeTomcat
QuerySurge Statsmon
QuerySurge Agent(s)

Articles in this section

Related articles