Administering VirtServer

This section covers essential tasks for administering VirtServer and configuring the command-line interface (CLI). It includes instructions for setting up and managing proxy configurations, logging in and out of VirtServer, and handling both SmartBear ID-based and file-based licenses via the CLI. Use these commands and examples to effectively configure proxies, manage licenses, and perform administrative tasks to ensure the smooth operation of VirtServer.

Proxy in VirtServer Application and CLI

By default, the VirtServer application uses ReadyAPI's proxy settings. To run VirtServer with a proxy, install ReadyAPI on the same machine and configure the proxy settings in ReadyAPI. To use VirtServer with a proxy independently of ReadyAPI, follow the instructions in the Proxy Settings section of the VirtServer Settings File page.

You can also configure proxy settings for VirtServer’s CLI, which requires its own configuration. For setup instructions, see the Proxy Commands for CLI and Proxy Command Examples for CLI sections on this page.

Proxy Commands for CLI

Set Proxy

The -setproxy command is used to set the proxy configuration details.

Usage:

-setproxy -proxytype <type> -proxymode <mode> -proxyhost <host> -proxyport <port> -proxyusername <username> -proxypassword <password> -proxyexcludehosts <exclude_hosts>

Example:

-setproxy -proxytype https -proxymode manual -proxyhost localhost -proxyport 8080 -proxyusername user -proxypassword pass -proxyexcludehosts yahoo.com,google.com

Flags:

Table 7. 

Name

Description

-proxytype <type>

The type of proxy (For example, http, https, socks).

-proxymode <mode>

The mode of the proxy (For example, manual, automatic).

-proxyhost <host>

The host address of the proxy server.

-proxyport <port>

The port number of the proxy server.

-proxyusername <username>

The username for proxy authentication.

-proxypassword <password>

The password for proxy authentication.

-proxyexcludehosts <exclude_host>

A comma-separated list of hosts to exclude from proxying (For example, yahoo.com,google.com).



Update Proxy

The -updateproxy command is used to update specific fields of the proxy configuration. Only provide the flags for the fields you want to update. To remove a value, use an empty string "".

Usage:

-updateproxy [flags]

Example:

-updateproxy -proxymode automatic -proxytype http -proxyexcludehosts ""

Flags:

Table 8. 

Name

Description

-proxytype <type>

The type of proxy (For example, http, https).

-proxymode <mode>

The mode of the proxy (For example, manual, automatic).

-proxyhost <host>

The host address of the proxy server to update.

-proxyport <port>

The port number of the proxy server to update.

-proxyusername <username>

The username for proxy authentication to update.

-proxypassword <password>

The password for proxy authentication to update.

-proxyexcludehosts <exclude_host>

A comma-separated list of hosts to exclude from proxying to update.



Remove Proxy

The -removeproxy command is used to remove the proxy configuration, after which the CLI will communicate directly with other systems without using a proxy.

Usage:

-removeproxy

List Proxy

The -listproxy command is used to print the current proxy configuration details to the console.

Usage:

-listproxy

Proxy Command Examples for CLI

Setting a Proxy

This command sets a manual HTTPS proxy on localhost with port 8080, username user, and password pass, and excludes yahoo.com and google.com from proxying.

-setproxy -proxytype https -proxymode manual -proxyhost localhost -proxyport 8080 -proxyusername user -proxypassword pass -proxyexcludehosts yahoo.com,google.com

Updating a Proxy

This command updates the proxy mode to automatic, changes the proxy type to http, and removes any hosts from the exclude list.

-updateproxy -proxymode automatic -proxytype http -proxyexcludehosts ""

Removing a Proxy

This command removes the current proxy configuration.

-removeproxy

Listing Proxy Configurations

This command lists the current proxy configuration details on the console.

-listproxy

Note

VirtServer's CLI can be configured to work with Okta and Device login or Client Credentials flow. Refer to the OIDC configuration page for instructions on how to set up Okta and initiate login using these flows.

Once authenticated, the commands on this page are available based on the access role and privileges.

SSL certificate validation in VirtServer CLI

VirtServer works through the HTTPS protocol. To secure the traffic, VirtServer uses a Certificate Authority (CA) certificate located in the <VirtServer>/bin/.virtserverkeystore file.

You may want to replace the default certificate with your own. This can be:

  • A trusted certificate, or

  • A self-signed certificate that you generate for your purposes for free.

This process is explained here.

By default, we will use the self-signed certificate to communicate with VirtServer. If you use a custom self-signed certificate for VirtServer, you must also configure the same certificate in the CLI to ensure secure communication.

Steps to Configure a Custom SSL Certificate in the CLI

  1. Copy the cacerts File.

    Copy the cacerts from one of the following locations:

    • VirtServer’s Java directory: VirtServer\jre\lib\security\cacerts

    • Default Java location (if the CLI is used separately): Program Files\java\jdk\lib\security\cacerts

  2. Import the Custom Certificate.

    Add your custom certificate to the cacerts store using the following command:

    keytool -importcert -alias <alias-name> -keystore cacerts -file <cert1.cer> -storepass changeit.

    Table 9. 

    Parameter

    Description

    <alias-name>

    The alias name for the certificate.

    <cert1.cer>

    The certificate file to add to the cacerts.

    changeit

    The default password for Java's cacerts truststore.



  3. Export the Certificate (If Using a Keystore).

    If you have a keystore and not a certificate, export the certificate using the command below:

    keytool -exportcert -alias <alias-name> -keystore <.keystore> -file cert1.cer -storepass <password>.

    Table 10. 

    Parameter

    Description

    <alias-name>

    The alias name of the certificate in the keystore.

    <.keystore>

    The path to the keystore where the certificate is stored.

    <cert1.cer>

    The file where the exported certificate will be saved.

    <password>

    The password for the keystore.



    After exporting, proceed to Step 2 to import the certificate into cacerts.

  4. Configure the Truststore in cli.properties.

    Once the certificate is added to cacerts, configure the truststore in cli.properties located at .readyapi\virt-server\keys\cli.properties:

    trustStorePassword=path/to/cacertstrustStorePath=truststore password (the default password is changeit for Java's cacerts)

    Table 11. 

    Parameter

    Description

    trustStorePath

    The path to the cacerts file.

    trustStorePassword<cert1.cer>

    The truststore password (default: changeit).



Note

If you do not copy the cacerts file to a separate folder, you’ll need to re-add the certificate after upgrading your Java version.

Log in to VirtServer

To perform any tasks using the command line interface, you must first log in. To do that, use the following command:

<path>/virtserver-cli -login -s IP:port -u name -pw password

For example:

"c:\Program Files\SmartBear\VirtServer\bin\virtserver-cli.bat" -login -s 10.0.81.128:9090 -u John -pw pswd1

Note

If your VirtServer is configured for OIDC, you are required to use Device Login to authenticate with your OIDC provider. Once authenticated, CLI features will become available. Refer to the OIDC page for further details.

The command uses the following arguments:

Argument

Description

-login, or

--login

Commands VirtServer to send a token that will be stored on the computer and used for authenticating other commands. The expiration time of the token is controlled by the timeout settings of VirtServer.

-s IP:port, or

‑‑server IP:port

Optional. The IP address and port of the VirtServer instance to which you are logging in. For example, ‑s 192.168.1.12:9090.

If you omit this argument, the utility uses the address specified in the previous command.

-u user-name, or

‑‑user user-name

Required. The user account for interacting with VirtServer. This can be the user account you created when running VirtServer for the first time or an account you added later.

-pw password, or‑‑password password

Optional. The password of the user you specified in the -u argument.

Tip

If you don't want to enter your password as a part of the command because it will be visible, omit the -pw argument. In this case, VirtServer will prompt you to enter the password in the command line. The password won't be visible when you are entering it.

Important

Important: In VirtServer 3.2.0, the use of the -u and -pw arguments with commands other than -login has been deprecated.

Managing SmartBear ID-Based Licenses via CLI

We are updating support for managing VirtServer via the command line. We have added activation and deactivation of a SmartBear ID-based license to the CLI. This is a separate utility to the previous behaviour which managed license activation and deactivation upon startup.

Activating and Deactivating a SmartBear ID-Based License

To activate a SmartBear ID-based license via CLI (where SmartBear hosts the license on its online license server), use the following format:

<path>/virtserver-cli -activatelicense
-licenseaccesskey -licenseissuer SLM

For example:

"c:\Program Files\SmartBear\VirtServer\bin\virtserver-cli.bat"
-activatelicense
-licenseaccesskey 3881e8c2-7898-4d5c-aa6e-2e47fc5e2538 -licenseissuer SLM

To activate a SmartBear ID-based license hosted on customer premises via CLI, use the following format:

<path>/virtserver-cli -activatelicense -licenseserver
-licenseaccesskey -licenseissuer SLM

For example:

"c:\Program Files\SmartBear\VirtServer\bin\virtserver-cli.bat"
-activatelicense -licenseserver http://181.72.180.195:40892
-licenseaccesskey 3881e8c2-7898-4d5c-aa6e-2e47fc5e2538 -licenseissuer SLM

To activate a SmartBear ID Based license hosted on customer premise via CLI and where OIDC is configured, please use the following format:

The CLI install command is updated to support client id and client secret.

<path to cli>/virtserver-cli -activatelicense -licenseserver --clientid-clientsecret-licenseissuer SLM

Note

Here:

  • -licenseserver is your on-prem license server URL.

  • -clientid is the client ID generated in the on-prem server.

  • -clientsecret is a client secret generated in the on-prem server.

For example:

"c:\Program Files\SmartBear\VirtServer\bin\virtserver-cli.bat"-activatelicense -licenseserver http://181.72.180.195:40892-clientid 2341-3243-1234-2432 -clientsecret 4323-reww-34534-rtw -licenseissuer SLM"c:\Prog -licenseissuer SLM

For instructions on finding your access credentials, visit the SLM licensing documentation.

To deactivate a SmartBear-hosted ID-based license via CLI (where SmartBear hosts the license on its online license server), use the following format:

<path>/virtserver-cli -deactivatelicense -licenseaccesskey-licenseissuer SLM

For example:

"c:\Program Files\SmartBear\VirtServer\bin\virtserver-cli.bat"-deactivatelicense -licenseaccesskey 3881e8c2-7898-4d5c-aa6e-2e47fc5e2538-licenseissuer SLM

To deactivate a SmartBear ID-based license via CLI, use the following format:

<path>/virtserver-cli -deactivatelicense -licenseserver
-licenseaccesskey -licenseissuer SLM

For example:

"c:\Program Files\SmartBear\VirtServer\bin\virtserver-cli.bat"
-deactivatelicense -licenseserver http://181.72.180.195:40892
-licenseaccesskey 3881e8c2-7898-4d5c-aa6e-2e47fc5e2538 -licenseissuer SLM

Argument

Description

-activatelicense, or

--activatelicense

Required: Activate a SmartBear ID-Based License.

-deactivatelicense, or

--deactivatelicense

Required: Deactivate a SmartBear ID-Based License.

-licenseserver, or

--licenseserver

Required: Specify the on-premises SLM License Server. You will need to request this from your license administrator.

-licensekey, or

--licenseaccesskey

Specify the access key if authentication is set on your SLM onpremise License portal. You will need to request support to access the portal from your license administrator.

-licenseissuer, or

--licenseissuer

Specify that this is an SLM license (this is a different license type from our legacy file-based license, which has a licenseissuer=JPROD).

-getlicense, or

--getlicense

Get information about the installed license.

Note

If your VirtServer is configured for OIDC, you are required to use Device Login to authenticate with your OIDC provider. Once authenticated, CLI features will become available. Refer to the OIDC page for further details.

Activating and Deactivating a File-Based License

While we are asking customers to switch to ID-based licensing due to the upcoming retirement of legacy file-based (ProtectionLS) licensing model, we have extended CLI support for this licensing model. This replaces the activation and deactivation of the license during VirtServer upstart.

To activate a file-based floating license via CLI, use the following format:

<path>/virtserver-cli -activatelicense -licenseserver
-licenseaccesskey -licenseissuer JPROD

For example:

"c:\Program Files\SmartBear\VirtServer\bin\virtserver-cli.bat"
-activatelicense -licenseserver http://181.72.180.195:443
-licenseissuer JPROD

To activate a file-based fixed license through CLI, use the following format:

<path>/virtserver-cli -activatelicense --licensefile (file)-licenseissuer JPROD

For example:

"c:\Program Files\SmartBear\VirtServer\bin\virtserver-cli.bat"
-activatelicense --licensefile (file)-licenseissuer JPROD

To deactivate a file-based license through CLI, use the following format:

<path>/virtserver-cli -deactivatelicense

For example:

"c:\Program Files\SmartBear\VirtServer\bin\virtserver-cli.bat"
-deactivatelicense

Argument

Description

-activatelicense, or

--activatelicense

Required: Activate a file-based License.

-deactivatelicense, or

--deactivatelicense

Required: Deactivate a file-based License.

-licensefile, or

--licensefile or (file)

Required for file-based fixed license: Specify the path to the legacy fixed license file.

-licenseserver, or

--licenseserver

Required for file-based floating license: Specify the on-premises ProtectionLS License Server. You may need to request this from your license administrator.

-licenseissuer, or

--licenseissuer

Required should be licenseissuer JPROD to specify that this is an JPROD license (this is a different license type to our ID-based license which has a licenseissuer SLM).

-getlicense, or

--getlicense

Get information about the installed license.

Log out of VirtServer

When you have finished working with VirtServer, log out by using the following command:

<path>/virtserver-cli -logout -s IP:port

For example:

"c:\Program Files\SmartBear\VirtServer\bin\virtserver-cli.bat" -logout -s 10.0.81.128:9090

The command uses the following arguments:

Argument

Description

-logout, or

--logout

Commands VirtServer to delete the stored session token that is used for authenticating commands.

-s IP:port, or

‑‑server IP:port

Optional. The IP address and port of the VirtServer instance you are logging in to. For example, ‑s 192.168.1.12:9090.

If you omit this argument, the utility uses the address specified in the previous command.

See Also

In this section:
© 2025
Publication date: