Administering VirtServer CLI

Applies to VirtServer 3.24.0, last modified on December 20, 2024

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 smooth operation of VirtServer.

Proxy in VirtServer Application and CLI

VirtServer application uses ReadyAPI’s proxy settings. If you require VirtServer to work with Proxy, please install ReadyAPI on the same machine and configure the proxy in ReadyAPI.

VirtServers CLI can also be configured for proxy and for this, it requires its own configuration. Please refer to the commands and examples for instructions on configuring Proxy in CLI.

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

    Flags:

    Name Description
    -proxytype <type>

    The type of proxy (e.g., http, https, socks).
    -proxymode <mode>

    The mode of the proxy (e.g., 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 (e.g., 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

    Flags:

    Name Description
    -proxytype <type>

    The type of proxy to update (e.g., http, https).
    -proxymode <mode>

    The mode of the proxy to update (e.g., 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 Configuration

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

-listproxy
Note:

VirtServers CLI can be configured to work with Okta and Device Login or Client Credentials flow. Please 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.

    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>.

    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/cacerts
    trustStorePath=truststore password (the default password is changeit for Java's cacerts)
    Parameter Description
    trustStorePath The path to the cacerts file.
    trustStorePassword 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. Please 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: 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-hosted ID Based license via CLI (where SmartBear hosts the license on its online license server), please 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 premise via CLI, please 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:

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

For instructions on finding your access credentials, please go to the SLM licensing documentation.

To deactivate a SmartBear-hosted ID Based license via CLI (where SmartBear hosts the license on its online license server), please 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 hosted on customer Premise via CLI, please 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

Not required if your license is SmartBear-hosted: This argument can be fullly removed as the CLI will point to the SmartBear license Server by default.

Required only if you host an on-premise SLM license server: Specify the address of the on-premise SLM License Server (hosted on your environment). You will probably need to request this from your license administrator.
-licensekey, or
--licenseaccesskey

Always required if your license is SmartBear-hosted: The access key is mandatory if your license is hosted with SmartBear. This is the access key generated for the VirtServer Admin after license is assigned and the admin has logged into manage.smartbear.com.

Required only if you use on-premise license server with authentication configured: You must specify the access key if authentication is set on your SLM on-premise License portal. You will need to request information to access the on-premise license portal from your license administrator.

Not required if your onpremise SLM license server is enabled for access for everyone: Your SLM onpremise License portal does not require users to be authenticated and it is enough to point VirtServer at the onpremise SLM license server for a license to be acquired.
-licenseissuer, or
--licenseissuer

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

Get information about installed license.
-clientid

Unique identifier for the On-Premise License Manager on the OIDC server.
-clientsecret

Unique string paired with the Client ID value for the On-Premise License Manager on the OIDC server.

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. Please 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 activation and deactivation of license during VirtServer upstart.

To activate a file-based floating license via CLI, please 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 via CLI, please 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 via CLI, please 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 path to the legacy fixed license file.
-licenseserver, or
--licenseserver

Required for file-based floating license: Specify the onpremise 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 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 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.

See Also

Command-Line Interface Utility
Managing Virts with the CLI
Connect With ReadyAPI
VirtServer Tutorial
VirtServer Command-Line Arguments

Highlight search results