__Include: VE License Management Overview for Charon-AXP/VAX

The Charon emulator kit itself does not include VE license management tools. The following actions must be performed on the VE license server. However, the VE license server can be on the same system as the Charon emulator.

Please note:

If you have not installed the license server yet (and for any more in-depth information), please refer to the VE license server user's guide
(see Licensing Documentation).
The information below shows the command-line tools for license management. Starting with version 1.1.16 of the VE license server, these activities can also be performed using a web-based management GUI. Please refer to the appropriate VE license server user's guide (see chapter VE License Server Web-based Management GUI in the VE license server documentation under Licensing Documentation).
For Charon-AXP/VAX, VE license support is only available for the Linux-based products.

This section describes some important aspects of a VE licensing environment:

VE License Server Certificates Overview

Custom certificate support for VE licensing is planned for Charon-AXP version 4.12 or later.

This section provides a short overview of the certificates used by the VE license server and Charon-AXP/VAX. Please refer to the VE license server documentation for details.

The VE license server uses certificates for different purposes:

License server operation: encrypted communication between license server and license clients (emulators).
- New certificate support in the VE license server started with version 2.1.3. Changed certificate names starting with VE license server 2.2.2.
- New certificate support for Charon-AXP/VAX is planned for version 4.12 or later (only new certificate names will be applicable).
Web-based management GUI: encrypted (HTTPS) communication between the integrated license server web server and web browsers. Starting with VE license server version 2.1.4, the name of the certificate and its management changed. Please refer to the VE license server documentation.

Important information:

General VE license server configuration:
- The VE license server will – by default – use the old certificates. Therefore, compatibility with existing Charon clients will be maintained during an upgrade of the license server.
- If the new certificates (using pre-defined names) are present in /opt/license-server/certs, these will be used and clients will have to use matching certificates. Please refer to the VE license server documentation for information how to activate the new certificates and, if desired, create custom certificates.
Checking if the new certificates are enabled in a Charon-AXP/VAX installation:
- Certificate location: /opt/charon/bin/certs
- Sample certificate names: ca.crt.sample, charon.crt.sample, and charon.key.sample
- If the directory contains the above files without the .sample suffix (e.g., ca.crt, charon.crt, charon.key), the new certificates have been enabled. On the license server, the sample files (for root CA and license server) are in /opt/license_server/certs. Please see the VE License Server guide in License Documentation for more information.
Make sure you understand the implications and possible side-effects before changing the certificate configuration. Incorrect configurations can lead to the loss of license access and interruptions in operation.

Firewall Considerations

If the VE license server is not installed on the same system as the emulator, any intermediate firewall must allow at least the port on which the license is served. Optionally, the firewalls must allow the port on which the web-based GUI is available. These ports are configurable on the VE license server. The default values are the following:

Default port on which licenses are served by the VE license server: TCP 8083.
Default port on which the web-based GUI runs: TCP 8084.

Creating a C2V File on a VE License Server

Running esxi_bind before First C2V Creation on VMware

Only required if the license server is to be run on VMware!

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:

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

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

Creating a VE C2V File and Sending it to Stromasys

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:

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 physical server; for an instance installed from a prepackaged Charon VE marketplace image, use centos)
3. <license-server-ip> is the ip address of your license server system
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 --filename <my-file>.c2v --platform <my-platform>
  where
  1. <my-file>.c2v is the path and name under which you want to store the fingerprint. The file type is C2V (customer-to-vendor)
  2. <my-platform> indicates the platform on which the license server runs (possible values: physical, aws, oci, gcp, azure, ibm, nutanix, or esxi).
Copy the resulting C2V file to your local system (unless you can send email from the license server system).
Send the C2V file to the Stromasys orders department (email address will be provided by Stromasys).

Installing a VE V2C File on a VE License Server

In response to the C2V file, Stromasys will send you a V2C file. This file contains the license data and is installed on the license server using the v2c utility.

Perform the following steps to install the license on the license server:

Copy the V2C file to the license server (e.g., with SFTP).
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 your physical server; for an instance installed from a prepackaged Charon VE marketplace image, use centos)
3. <license-server-ip> is the ip address of your license server system
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 under which you want to store the fingerprint. The file type is V2C (vendor-to-customer).

After the installation of the V2C file, the license server will be restarted.

Viewing the License on a VE License Server

The license data can be viewed via the web-based GUI of the VE license server (see Licensing Documentation). It can also be viewed with the license_viewer program using the following steps:

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 your physical server; for an instance installed from a prepackaged Charon VE marketplace image, use centos)
3. <license-server-ip> is the ip address of your license server system
Become the privileged user and run the license_viewer program.
1. Become the root user: # sudo -i
2. Run the license_viewer program: # /opt/license-server/license_viewer

Charon-AXP/VAX Emulator License Configuration

The license server must be added to the Charon emulator configuration.

Relevant parameter:

set session license_key_id = "VE://<license-server-IP>[:<port>]/[<passphrase>/]"

Where the following parameters are used:

<license-server-IP>: the IP address of the VE license server (127.0.0.1 if the VE license server is on the same host).
<port>: the TCP port on which the license is served (if not specified, the default port 8083 will be used).
<passphrase>: the passphrase of the correct product section on the license (optional). The parameter may be required for the emulator in some cases to identify the correct section.

To configure a backup license server, add the backup license server information to the same line after the primary license server information:

set session license_key_id = "VE://<primary-licserv-IP>[:<port>]/<passphrase>/, VE://<backup-licserv-IP>[:<port>]/<passphrase>/"

Only one backup server can be configured. The backup server typically provides a license limited to a certain number of runtime hours should the primary server become unavailable. If all valid licenses are lost or removed while an emulator is running, there is a grace period (configured on the license; default: 2 hours). The grace period is the time period during which the emulator continues to run after its license has been lost or removed. If there is no valid license after the grace period ends, the emulator will stop (this could cause data loss for a running guest system).

Updating an Existing License

If you need to update an existing license, for example because the time limit on the license has expired or to upgrade to a new product versions, perform the following tasks:

Generate the C2V file for the existing license. This Customer-to-Vendor (C2V) file contains the license characteristics necessary for creating the license update.
Send the C2V file to Stromasys. Stromasys will use the data to create the necessary license update. You will receive a V2C file (the Vendor-to-Customer file).
Apply the license data from the V2C file(s) on the license server. This will install and activate the update for your license.