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 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 QuerySurgeTomat 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
Preliminary Task - Obtain a Certificate
In order to deploy with HTTPS/SSL, you will need to obtain a Certificate ("cert") 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. In addition, you may need to work with an admin in your organization to obtain and deploy the cert, as organizations may have specific procedures for this. The cert file will most likely have the ".crt" extension, but other extensions are possible.
Note: The CSR (Certificate Signing Request) required to obtain the cert for your QuerySurge App Server must be generated from the keystore of your QuerySurge App Server, so you will need to work with a network or security admin to start the process of obtaining a cert for your App Server. The instructions below use the default keystore for the Java that QuerySurge distributes with.
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
- QuerySurgeMySQL (optional shutdown)
2. Import your CERT to the QuerySurge App Server KeyStore
Locate your certificate file 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 keystore (
cacerts), using the following command:
keytool -import -alias <your alias> -file <your certificate file> -keystore cacerts
The 'alias' is an alias to this entry in the keystore. The 'file' is the cert file that has been obtained for the QuerySurge App Server.
Note: If prompted for a password while importing the cert, the default password for the cacerts keystore 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 keystore based on how and where you are calling this command. In the example above, we navigate to QuerySurge's keystore directory and call the keytool using the fully qualified path name. This applies to the keytool commands in the later steps as well.
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
keystorePass, as shown below:
<!-- Define a SSL HTTP/1.1 Connector on port 8443
This connector uses the JSSE configuration, when using APR, the
connector should be using the OpenSSL style configuration
described in the APR documentation -->
<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" />
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 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:
<!-- <Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443" /> -->
4. Export your CERT from the QuerySurge App Server Keystore and Import into Agent and Statsmon Keystores
For multi-machine installations where multiple QuerySurge Agent(s), and the QuerySurge Statsmon service are running on different machines, you'll need to export a cert and import it on each Agent machine 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 and to the Statsmon machine (again, this is the QuerySurge Database machine). On the Agent and/or Statsmon (i.e., database) machines, 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
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
You can find the
agentconfig.xml file at:
/<QuerySurge Install Dir>/QuerySurge/agent/config/. In the default install, this path is:
- 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:
- 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/.
7. Re-start your QuerySurge Services
Start the services in the reverse of the order you stopped them in:
- QuerySurgeMySQL (if shutdown, restart this first)
- QuerySurge Statsmon
- QuerySurge Agent(s)