Contents

Important Information to Protect the License Validity

Certain actions can invalidate your license. Therefore, once you have installed your license, please note the following points:

For cloud deployments: if supported by the cloud provider, the VE license server instance can be moved to a different subnet, as long as the original instance can be moved.

It is also possible to backup and restore (to the same instance) the license server data. Please note that is not possible to use such a backup to revert to a previous license version.

However, the following actions will invalidate the license:

1. All supported VE license server platforms:
   • Copying the license server data to a different instance.
   • Seriously damaging the root filesystem of the license server system.
   • Re-installing the license server system.
   • Copying the virtual machine on which the license server runs. This includes cloning a virtual machine, or recovering a backup into a new virtual machine.
   • Changing the number of CPU cores of the license server system.
2. VMware VE license server platforms:
   • Restrictions from point 1 above.
   • If the license server is bound to the ESXi host: using vMotion on the VM in which the VE license server runs.
   • If the license is bound to a vCenter server:
     • Using vMotion to move the VM in which the license server runs to a system not controlled by the same vCenter.
     • Restoring the license server from a backup or snapshot and rebinding the restored license server to a new vCenter server (e.g., DR case).
   • Changes to the API interface of the ESXi host or vCenter Server.
   • The license can become temporarily unavailable if the user credentials or address information recorded by esxi_bind are changed. In this case, esxi_bind must be run again to define the correct user credentials and address information.
3. AutoVE license server platforms:
   • Restrictions from point 1 above.
   • Charon emulator host instance register with their license server only once at start.
     This is recorded on the license server in /opt/license-server/instances.db.
     If this file is lost, the license is not invalidated from the license server's point of view, but it can no longer be used from the Charon host instances as they will not register a second time. The Charon host instances would have to be recreated (fresh instance launch from a supported marketplace instance). Therefore, it is very important to backup up the instance database file. If a peer license server is used, the databases are synchronized between the two servers providing another level of data backup.
   • If the virtual hardware of the Charon emulator host is changed significantly (for example, the number of CPUs), then the registration of the Charon emulator host with the license server will be invalidated requiring that a new instance to be launched.
   • AutoVE server and Charon host instance must be in the same cloud and the Charon host instance must be launched from a supported AL marketplace image.
4. Physical VE license server platforms:
   • Restrictions from point 1 above.
   • Replacing the boot disk (i.e., the disk on which the operating system is installed).

If your license is invalidated for whatever reason and you cannot revert the action that caused the invalidation, you must request a new license from Stromasys. Therefore, planning your license infrastructure should include a backup license server to insure continuity until you received your new primary license.

Overview - Requesting and Installing a License

Overview of the basic steps to request and install a license:

• VMware only: for the first license request in a VMware environment, or if the binding data has changed, use the esxi_bind command to bind the license server to its ESXi host or vCenter Server.
• Collect the fingerprint (the customer-to-vendor - or C2V - file) on the license server and (if applicable) the backup license server.
• Send the fingerprint data to Stromasys.
• Stromasys will send you a license. This is a V2C file with the license data and a text file with human readable license content.
• Install the license data (the vendor-to-customer - or V2C - file) on the license server and (if applicable) on the backup license server.
• Verify the license installation.

These basic steps are described in more detail below.

License Installation Using the Command-Line

The following sections will show how to perform a license installation on the VE license server. Alternatively, you can use the web-based GUI (see VE License Server Web-based Management GUI)

Running the esxi_bind Command (VMware environment only)

The esxi_bind command sets up the necessary communication connection between the VE license server and the ESXi host / the vCenter Server.

It must be run on the license server (and the backup license server, if applicable):

• once before the first license is requested, and
• again should the user credentials, the password, or the address data for the access to the ESXi host / the vCenter Server change. Please make sure that the password of the selected user account does not automatically expire after a certain time period. This would cause disruptions in the license server operation and make it impossible for clients to receive their license.

Perform the following steps:

1. Use ssh to log in on the license server instance (assuming that username/password login is possible for an on-premises VMware installation).
   # ssh <user>@<license-server-ip>
   where
   
   1. <user> is the user for interactive login associated with your license server system
   2. <license-server-ip> is the ip address of your license server system
      
2. Become the privileged user on the license server and run the esxi_bind program.
   1. Become the root user: # sudo -i
   2. Run the esxi_bind program:
      # /opt/license-server/esxi_bind -a <address> -u <username> -p <password>
where
      1. <address> is the IP address of the ESXi host or vCenter Server

      2. <username> is a user on the ESXi host or vCenter Server (see notes below).

      3. <password> is the password of the user
3. If the command is successful, it will create the file /opt/license-server/config.ini containing the connection data (the password is encrypted).

Important notes regarding the user on the ESXi host or the vCenter Server:

1. The username on the vCenter Server can take different forms:
   
   • Simple username
     esxi_bind parameter example:    -u myusername
   • Username includes a domain name in one of the following two formats:
     • <domain>\<username>
       esxi_bind parameter example (quotes are mandatory):    -u 'mydomain\myusername'
     • <username>@<domain>
       esxi_bind parameter example:    -u myusername@mydomain


2. The user must have at least the following global permissions (i.e. the permissions cannot be limited to a specific VM):

   • Datastore > Allocate Space
   • VirtualMachine > Config > AddNewDisk
   • VirtualMachine > Config > RemoveDisk

Please note: if username and/or password contain Unix shell meta-characters, these characters must be escaped (enclose the string in single quotes, or add a backslash character in front of the meta-character).

Collecting the Fingerprint Data on the License Server

The fingerprint is collected on the license server using the c2v utility.

Perform the following steps to collect the fingerprint on the license server and (if applicable) the backup license server:

1. Use ssh to log in on the license server instance.
   # ssh -i ~/.ssh/<mykey> <user>@<license-server-ip>
   where
   1. <mykey> is the private key of the key-pair you associated with your cloud instance
      (for an on-premises VMware installation where login with username/password is allowed, it is not needed)
   2. <user> is the user for interactive login associated with your license server instance (e.g., opc on OCI, centos for a CentOS instance on AWS, or the custom user on your VMware virtual machine or your physical server;
      for an instance installed from a prepackaged Charon supported marketplace image, use sshuser for Charon-SSP and centos for Charon-PAR)
   3. <license-server-ip> is the ip address of your license server system
      
2. Become the privileged user and run the c2v program.
   1. Become the root user: # sudo -i
   2. Run the c2v program: # /opt/license-server/c2v [-a] --filename <my-file>.c2v --platform <my-platform>
where
      1. The optional -a parameter creates the fingerprint for a AutoVE license. General VE mode and AutoVE mode are mutually exclusive.
      2. <my-file>.c2v is the path and name under which you want to store the fingerprint. The file type is C2V (customer-to-vendor)
      3. <my-platform> indicates the platform on which the license server runs (possible values: physical, aws, oci, gcp, azure, ibm, nutanix, or esxi; for AutoVE: aws, oci, gcp, azure)
3. Copy the resulting C2V file to your local system (unless you can send email from the license server system).

Sending the C2V File to Stromasys and Receive License Data File

Stromasys or your Stromasys VAR will provide you with an email address to which you should send the C2V file you created in the previous step.

Please also indicate the following:

• License requirements based on your contract with Stromasys (product version, number of concurrent instances, is this the main or the backup license, etc.).

• In case of a license update, specify clearly what should be changed and what should remain the same.
• Do you require a license with or without a passphrase (can be configured per product section)?
  • The use of a passphrase requires VE license server versions 1.1.x and higher.
  • The use of a passphrase requires Charon-SSP emulator versions 4.3.x and higher.
  • For Charon-PAR, a passphrase is mandatory. It is required to identify the correct license section.
• Do you require an AutoVE license?
  • Available starting with VE license server version 1.21 for supported cloud-specific Automatic Licensing marketplace images.

In response, you will receive two files:

• The so-called V2C (vendor-to-customer) file which contains the license data. The content of the license (type of emulated hardware, expiration date, number of concurrent instances, etc.) depends on your contract with Stromasys.
• A text file containing the license content in human readable form. Starting from November 2023, the text file will contain the checksum of the V2C file for integrity checking. Please review the text file carefully before installing the license to make sure the content is what you expected.

It is strongly recommended to keep the V2C and text files to have a record of licenses received and updated over time.

Installing the License Data on the License Server

Please review the text file carefully before installing the license to make sure the content is what you expected.

The license data is installed on the license server using the v2c utility.

Perform the following steps to install the license on the license server (if a backup license server is to be used, it needs its own license):

1. Copy the V2C file to the license server (e.g., with SFTP).
2. Use ssh to log in on the license server instance.
   # ssh -i ~/.ssh/<mykey> <user>@<license-server-ip>
   where
   1. <mykey> is the private key of the key-pair you associated with your license server instance
      (for an on-premises VMware installation where login with username/password is allowed, it is not needed)
   2. <user> is the user for interactive login associated with your license server instance (e.g., opc on OCI, centos for a CentOS instance on AWS, or the custom user on your VMware virtual machine or you physical server;
      for an instance installed from a prepackaged Charon supported marketplace image, use sshuser for Charon-SSP and centos for Charon-PAR)
   3. <license-server-ip> is the ip address of your license server system
      
3. Become the privileged user and run the v2c program.
   1. Become the root user: # sudo -i
   2. Run the v2c program: # /opt/license-server/v2c -f <my-file>.v2c
where <my-file>.v2c is the path and name of the V2C (vendor-to-customer) file.
      Starting with VE license server version 1.1.23, the v2c tool will show the difference between old and new license for a license update and require confirmation. Please review the differences carefully before confirming.

After the installation of the V2C file, the license server will be restarted. This restart will not affect running emulators. However, depending on the emulator product, it could be that the license server does not correctly display the license usage (license_viewer -u  output and license server log file) until the emulators connect to the license server again after the next check interval has expired (default 1 hour).

Please note:

• Please note that to install a license with a new license ID (or another changed static parameter - see below), the old license must first be removed in an additional step (see Removing a License from a VE License Server in the applicable VE License Server Guide).
• In versions before 1.0.17, the license server will not start until a valid license has been installed.

The following example shows the initial installation of a V2C file:

$ sudo /opt/license-server/v2c -f mylicense.v2c 
<<V2C>> Going to import "mylicense.v2c" ...
<<V2C>> Imported "mylicense.v2c" successfully.
<<V2C>> Restarting license server ...
<<V2C>> Done

Please note:

• If the V2C file installed is an update to an existing license, the v2c command will first show the difference between old and new license and wait for the user confirmation before proceeding with the update. Please review the differences carefully before confirming. If absolutely necessary, this behavior can be suppressed using the -s option.
• To import the same license repeatedly will not cause a problem. In this case, the user will not be asked to confirm the import.
• The difference between old and new license is shown as a side-by-side list of the old and new license parameters. This list uses short parameter names to keep the old and new parameter on one line.

Verifying License Installation and License Content

Checking the License Server Log file

Check the license server log file to see if the server started successfully or reported an error. Use the following command (as the privileged user):
# cat /opt/license-server/log/license.log

The log should indicate that the license server is ready to serve licenses.

Using the license_viewer Program to Display the Content of a License

The license server provides a license_viewer program to view the content of the license. To run it, use the following command (as the privileged user):

# /opt/license-server/license_viewer

The following sample shows the output for several different licenses:

The license contains a key-specific section and one or more product-specific sections. Please note that the product-specific section is mostly not applicable to AutoVE licenses as this license is based on the number and configuration of the cloud-based host instances.

Important key-specific license parameters:

Important product-specific license parameters (most parameters not applicable to an AutoVE license):

License Installation Using the Web Interface

The license server provides a web interface to display important license characteristics, to display license client systems, and to enable license updates.

It is accessed using the URL https://<license-server-ip>:<web-gui-port> where

• license-server-ip is the address or the name of the VE license server, and
• web-gui-port is the port on which the web-server runs (default 8084).

Using just http://<license-server-ip> will cause a redirection to the configured HTTPS port (access to TCP port 80 required).

Prerequisite: access to TCP port 8084 of the license server (or an alternative port configured in the file /opt/license-server/config.ini file) must be possible.

The following image shows sample output of a general VE license for SSP:

The first section of the samples shows the basic characteristics of the license. The Product Section shows the licensed products and their characteristics.

See VE License Server Web-based Management GUI and Additional Configuration Options - the config.ini File for more information.