VirtServer Installation

Applies to VirtServer 3.20.0, last modified on May 28, 2024

VirtServer uses a separate installation package from ReadyAPI. You can install it on Windows, Linux and macOS. The ways to install the product on these operating systems are very similar. There are differences in installing the product on Linux headless (GUIless) machines. This topic provides detailed information on installation steps for both cases.

Before installing

To run VirtServer, your computer must meet certain system requirements.

Also, you will need either a VirtServer trial license or a commercial VirtServer license. To get a license, contact your sales representative or write to [email protected].

You install a license during the first VirtServer run.

Installing VirtServer With the Installation Wizard (Typical)

Follow these steps:

  1. Download the VirtServer installer for your platform (Windows, Linux or macOS, 32- or 64-bit) from the SmartBear website.

    Note: If you use Linux, check that the installer has correct permissions and is executable.
  2. Run the downloaded installation package.

  3. Follow the installation wizard instructions:


    Click the image to enlarge it.

    In case of updating existing installation


    Click the image to enlarge it.

    • Specify the installation directory. If you are upgrading to 3.18.0, we recommend installing VirtServer into a new folder location and manually deleting the folder for the previous version. We do this to enable a cleaner installation and to avoid possible issues following our recent upgrades to Java 17.0.4.

      Destination Directory

      Click the image to enlarge it.

    • On one of the steps, the wizard will ask you to select additional components to be installed:


      Click the image to enlarge it.


      Click the image to enlarge it.

  4. After selecting the desired components, click Finish to finish the installation.


    Click the image to enlarge it.

    Installing using unattended mode or response.var
    • If you prefer running the installer in unattended mode -q, you can configure using system properties -Dservice.install and -Dservice.autostart.

      See Examples

      • VirtServer-x64-3.19.0 sh -q -Dservice.install=truewill install the service, requires that the user is root.
      • -q -Dservice.autostart=truewill install the service and configure it to autostart when the operating system boots.
    • It is also possible to start VirtServer without root access by modifying the response.varfile file and setting arguments to represent how you require VirtServer to start. You can read more on this here.

      response.varfile is found in \VirtServer-3.XX.0\.install4j

      The arguments are:

      • install4j response file for ReadyAPI VirtServer320.0

        • SendAnalytics$Boolean=true
        • sys.adminRights$Boolean=true
        • sys.component.132$Boolean=true
        • sys.component.7667$Boolean=true
        • sys.component.7811$Boolean=false
        • sys.installationDir=C\:\\Program Files\\SmartBear\\VirtServer-3.19.0
        • sys.languageId=en
      • The corresponding components listed are:
        • #ReadyAPI VirtServer: sys.component.132
        • #ReadyAPI VirtServer Service: sys.component.7667
        • #Autostart Service: sys.component.7811
        • #Install JDBC drivers: sys.component.1154
      • Change to false or true as required e.g., to run without root access
        • sys.adminRights$Boolean=False
        • sys.component.132$Boolean=true
        • sys.component.7667$Boolean=false
        • sys.component.7811$Boolean=false
      • Use the command prompt to run the below. Check the path to the response file is correct before running. The installer runs in the background.
        • Win
          VirtServer-x64-3.19.0 exe -q -varfile <path to response.varfile>
        • Linux

          Requires superuser sudo to run.

          sudo sh ./VirtServer-x64-3.19.0 sh -q -varfile <path to response.varfile>
  5. If you prefer running the installer in unattended mode -q, you can configure using system properties -Dservice.install and -Dservice.autostart. See examples:

    • -q -Dservice.install=true will install the service, requires that the user is root.

    • -q -Dservice.autostart=true will install the service and configure it to autostart when the operating system boots.

After Installation Is Over

After the installation is over, run VirtServer, create a user on it and activate the VirtServer license. These actions are rather simple. Just follow the instructions you will see on the screen.

Note: If you work in an offline environment and need to activate an offline license, please refer to instructions to this page.

After installing VirtServer, you may want to replace the SSL certificates it uses or change the VirtServer port number.

VirtServer stores all the information (added virtual services, users, and so on) in a database file. We recommend that you periodically back up that database file.

How to schedule creating a backup
  1. Create a .bat script file that copies the database file:

    copy /Y %HOMEPATH%\.readyapi\virt-server\virt-server.h2.h2.db <Path to the backup folder>

  2. Open Task Scheduler and click Create Basic Task from the right toolbar:

    Creating scheduled task for backing up VirtServer database file

    Click the image to enlarge it.

  3. In the subsequent dialog, specify the name and description of the task. Click Next.

  4. At the Trigger step, specify when you want to back up the database. For example, to back it up once a week, select Weekly and select a day on which you want to copy the file:

    Selecting a trigger for backing up VirtServer database file

    Click the image to enlarge it.

  5. At the Action step, select Start a program and click Next.

  6. At the next step, in the Program/Script field, specify the path to the created script. Click Next:

    Selecting a script file that backs up VirtServer database file

    Click the image to enlarge it.

  1. Create an .sh script file that copies the database file:

    cp ~/.readyapi/virt-server/virt-server.h2.h2.db <Path to the backup file>
  2. Open the terminal and enter the following command:

    crontab -e

    It opens the text editor where you can schedule a task.

  3. At the end of the file, specify the line that commands cron to execute the created script. For example, to perform a backup each Friday, you could specify the following line:

    0 0 * * 5 <Path to your script>

    To learn more about the cron syntax, you can see the Ubuntu documentation.

Upgrading VirtServer

When upgrading or reinstalling VirtServer, please follow the same steps as defined above for installation. We recommend you perform a backup of your database using the steps defined below before you upgrade. This is a precautionary step. If you are upgrading VirtServer on the same machine as the original installation and have a license activated, this should be picked up when you restart VirtServer.

Installing on Docker

For users deploying VirtServer in Docker, please refer to the following page for guidance.

Installing on Headless Machines

VirtServer can be downloaded and installed on a headless machine using command line options. Once downloaded the installer will unpack files and then will continue the installation in the command-line mode.

The installer will ask you to perform the same actions that you perform in the GUI installer: specify the installation folder, choose the components to be installed, and so on. Follow the instructions you will see on the screen.

Customer Notice

H2 Upgrade and Migration:

We are upgrading the underlying H2 database to the latest V. 2.1. The upgrade will happen as part of your next upgrade and will migrate your data without you needing to do anything. New installations will use V. 2.1. However, we understand that you may have questions or in the event of the upgrade experiencing issues, please contact support if you need help before of during the upgrade process. You can also request a technical session with our Solution Engineering team if you would like some help. Please contact your SmartBear Account Manager to arrange.

What is this:

  • To manage storage of virts, tests, transactions and users, VirtServer uses a H2 database.
  • The version of H2 used in VirtServer and Testengine has been at V. 1.4 for a while now and, as part of an ongoing maintenance program, we are upgrading the product to the latest version at this time (currently V. 2.1 is latest for January 2023).
    • This also addresses potential vulnerabilities identified in CVE-2021-23463, CVE-2021-42392, CVE-2022-23221, CVE-2022-45868.
  • The H2 upgrade will be occur to those customers moving to V. 3.17 of VirtServer.
  • To make it easier for our customers, the upgrade process is automated. Any customer on a version previous to above (between V. 3.6 and 3.14), will see the start up script take them through the upgrade process with no actions required. Once the upgrade is complete, the product will start as normal.
  • Any customer on VirtServer version prior to VirtServer 3.6.0, please read on.

I am using a version of VirtServer earlier than 3.6.0:

I tried upgrading and I want to go back to 3.14 or earlier:

  • From October 2023, file-based licensing will no longer be available and will be fully replaced by SmartBear ID-based licensing - SmartBear ID-based licenses are a new license management option that we started using in ReadyAPI 3.8.1. Support for SmartBear ID-based licenses is now being added to VirtServer 3.16.0 and VirtServer 3.17.0. It is more reliable and convenient than the license type used in the previous product versions. As we approach the October milestone, we're actively encouraging customers to transition over, and now is the time to start planning that transition. You should engage with your SmartBear Account Manager immediately to understand the steps involved in transitioning and get started. Please read here to learn more.
  • To downgrade your version and install the correct H2 DB, please follow the following steps:
    • VirtServer: When upgrading the H2 database to V. 2.1, the old database was preserved by default. The customer could optionally remove this old database.
    • If the database is not removed, an older version of VirtServer can be started without any action. Note that the data in VirtServer will revert back to the state before the upgrade, so data might be missing.
    • If the old database was removed, customer needs to restore this from backup before running an older version of VirtServer. When the customer later decide to reinstall the newer version of VirtServer, the migrated database from the previous update should be removed before starting VirtServer or the new migration will not be triggered.

See Also

User Tasks

Highlight search results