Sessions 3.0.9 to 4.0.2 Load Balancer Upgrade Guide for Windows

To request assistance with upgrading or to obtain the links to self-upgrade, please click here to fill out the Upgrade Request Form.

Before you begin

  • This is the instruction to upgrade qTest Sessions v3.0.9, 3.0.10 to v4.0.2 on cluster or load balancing environment, where multiple instances of qTest Sessions were installed, and each instance is running on its own Windows server
  • qTest Sessions v4.0.2 only works with qTest Manager v8.7.3 or later
  • Make sure qTest Manager is running and your qTest license file has been imported
  • Make sure your server environment meets recommended hardware requirements

Below diagram shows a sample scenario of qTest Sessions 3.0.9 being installed on a cluster or load balancing environment.


Steps to upgrade to qTest Sessions 4.0.2 on Load Balancing environment

You will need to access to every Windows instance where qTest Sessions was installed (qTest Sessions Server #1 and qTest Sessions Server #2 in the above diagram) and perform steps to upgrade qTest Sessions to v4.0.2.

Step 1. Login to qTest Sessions Server

Step 2. Collect current qTest Sessions configurations

Right click on qTest Sessions icon in the system tray, then select 'Configure Instance...'


Note down all the configuration values including: running ports, database configurations, storage configurations, qTest Manager configurations. As highlighted in below screenshots.

qTest Sessions running ports:


Database configurations:


Storage configurations:


qTest Manager configurations


Step 3. Stop qTest Sessions

Right click on qTest Sessions icon in system tray, go to qTestSessionService - Running menu group and select Stop menu item 


Step 4. Install qtestctl and Configure qTest Sessions

Download qTest Sessions 4.0.2 at <DOWNLOAD LINK>

Extract downloaded file to C:\qtestctl

To configure qTest Sessions, navigate to extracted folder C:\qtestctl and edit ‘qtest.config’ file

Step 4.1. Make sure there is sessions item in apps list

apps = ['sessions']

Step 4.2. Configure qTest Sessions database

Go to postgres section and use the database configurations we collected in step #1 to configure database for qTest Sessions

  • postgres
    • host: Postgres server’s host name or ip address
    • port: Postgres server’s port
  • auth
    • user: username to authenticate with Postgres database server
    • pass: password to authenticate with Postgres database server
  • db:
    • qtest: qtest database’s name
    • session: session's database name
external {
  postgres {
    host = ''
    port = 5432
  auth {
      user = 'postgres'
      pass = 'root'   
  db {
      qtest = 'qtest'
      session = 'sessions'

Step 4.3. Configure qTest Sessions server

We will use qTest Sessions running ports, storage configurations, and qTest Manager configurations that we collected in step #1 to configure qTest Sessions server

In qtest.config file, navigate to section sessions in qtest.config file to configure qTest Sessions server.

  • port: configure server port that qTest Sessions will be listening
  • ssl: configure SSL if you want to deploy qTest Sessions with https protocol
    • enabled: set value to true to enable https
    • key: absolute path to .key file
    • cert: absolute path to .cert file
  • qtest: configure qTest Manager application URL and master token
    • host: qTest Manager URL
    • mastertoken: the token that qTest Sessions uses to connect to qTest Manager
  • storage: configure a location that qTest Sessions will store its data to either on disk or Amazon S3 storage. Make sure you change value of rootpath to reflect actual folder in the machine
    • type: type of the storage, possible value is amazon_s3 or disk_storage
    • accesskey: if storage type is set to amazon_s3, this is the access key used to access to Amazon S3 storage. Leave this field empty if storage type is set to disk_storage
    • secretkey: if storage type is set to amazon_s3, this is the access key used to access to Amazon S3 storage. Leave this field empty if storage type is set to disk_storage
    • bucketname: if storage type is set to amazon_s3, this is ame of the name of the bucket to store data on Amazon S3
    • rootpath: if storage type is set to disk_storage, this is the absolute path to a folder on disk where data is stored. In our example, we will use S:\

Below is an example of qTest Sessions server configuration:

sessions {
port: 9090
ssl {
enabled = false // set to true if you want to enable https
key = "/absolute/path/to/dist/ssl/server.key"
cert = "/absolute/path/to/dist/ssl/server.crt"
qtest {
host = ''
mastertoken: "QToy"
storage {
// value must in ['amazon_s3', 'disk_storage']
// amazon_s3: stores resource files on amazon ec2
// disk_storage: stores resource files on local disk
type = 'disk_storage'
// if stores resources on Amazon S3
accesskey = ''
secretkey = ''
bucketname = ''
// if stores resources on local disk
rootpath = 'S:\\'


Save and close qtest.config file when you are done.

Step 5. Backup data

Open command prompt and navigate to the extracted folder \qtestctl

Enter following command to backup qTest Sessions data.

> qtestctl sessions:backup

If the execution is successful, the backed up data is stored in \qtestctl\sessions\build\tmp

Step 6. Start qTest Sessions

> qtestctl sessions:start


If this step is successful, proceed to step #7.

Troubleshooting: if step above is not successful, you need to rollback qTest Sessions to version 3.0.9 (or 3.0.10) following below steps:

Restore backup data

> qtestctl sessions:restore

When restore process completed, perform the following step to completely rollback to qTest Sessions 3.0.9:

  • Start qTest Sessions 3.0.9 by right clicking on qTest Sessions icon in system tray, go to qTestSessionService - Stopped menu group and select Start menu item
  • Open <qTest Sessions URL>/admin page. Here <qTest Sessions URL> is the URL to access to your  qTest Sessions 3.0.9 in this server
  • Login with your admin account. Note: consult QAS customer support for the admin credentials
  • Go to elasticsearch menu item in the left panel
  • Click on 'Reindex Data' button on the right

After restored, contact customer support to troubleshoot the issue with upgrading qTest Sessions on Windows load balancing environment.

Step 7. Install qTest Sessions as a Windows service

Note: only proceed to this step when you have successfully performed step #6.

To enable qTest Sessions to automatically starts when Windows starts, we need to install it as a Windows service.

Open a Command Prompt if you haven't done so, and navigate to the extracted folder C:\qtestctl

Execute below command in your command prompt:

C:\qtestctl> Install.bat
C:\qtestctl> net start qtest

Step 8. Turn off qTest Sessions 3.0.9

Note: only proceed to this step when you successfully performed step #6.

Right click on qTest Sessions icon in the system tray, and select Exit.

Open command prompt and type 'services.msc' then press Enter. The Services window will be opened.

On Services window, look for a service named 'qTest Sessions Service v3.0.x', then right click on it and select Stop from popup menu.


Right click again on the service qTest Sessions Service v3.0.x then select Properties


Change Startup type to Disabled, and click OK.



Step 9. Repeat step #1 to #8 to upgrade qTest Sessions on another server 

Step 10. Verify

This step is to make sure qTest Manager is able to connect to the qTest Sessions through qTest Sessions Load Balancer.

9.1 Login to qTest Manager using Site Administrator account.

9.2 Go to Site Administration page and click on tab SYSTEM CONFIGURATIONS.

9.3 In MISCELLANOUS section, enter URL of qTest Manager, such as http://[qTest_Manager_IPAddress]:[Port] or https://[qTest_Manager_IPAddress]:[Port] if you installed qTest Manager with SSL certificate.


9.4 In QTEST EXPLORER | SESSIONS section, ensure the value of qTest Explorer | Sessions URL field is set to the public IP address of qTest Sessions Load Balancer, as below screenshot.


Now you can access to qTest Sessions site and verify the new version.



Powered by Zendesk