Connectware Licensing

Your Cybus Connectware installation is running according to the enabled features and expiration duration as set in the License.

Activating Connectware Online

Upon each start-up of Connectware, the license activation is done automatically, if Connectware has connectivity to the Internet as shown in the Internet connectivity section. In particular, the automatic license activation requires connectivity to the Cybus Portal backend at graphql-server.cybus.io.

If this connectivity is available, an extra update of the online activation can manually be triggered in the License View. This may be needed if the license details have been upgraded from Cybus, but Connectware does not show the updated information. Navigate to System -> License to see the License View showing the current license details.

../_images/license-view.png

To perform an online activation or renewal of the license, on the license detail view press the Refresh button, the second from right at the top. This will refresh the current license information over the Internet from the Cybus Portal.

../_images/license-refresh.png

Activating Connectware Offline

If the Connectware installation does not have Internet connectivity, you need to perform an offline activation of your license. These steps are described in the following text.

Most importantly, you need to retrieve a license file from the Cybus Portal, and upload this file into the offline Connectware. Below we describe several methods you can use to add the license file to your Connectware installation.

Downloading License File via Installer

If Connectware has been installed using the connectware-online-installer.sh shell script (as explained in this Cybus Learn article), the retrieval of the license file can also be performed by running this script with a different command line option --download-license-file. When using this script with this option, you need to supply the license key that was also necessary on initial Connectware installation. When calling the script, you can either specify the license key directly as command line option, or specify an installation directory on that computer where the Connectware instance is already installed.

To download the license by the script with the license key (e.g. ABCABCABC) available:

./connectware-online-installer.sh --download-license-file -k ABCABCABC

To download the license by the script if the Connectware target installation is in /opt/connectware:

./connectware-online-installer.sh --download-license-file -d /opt/connectware

In either case, the script will download the file and print the filename upon successful completion. This license file can subsequently be used to activate an offline instance of Connectware.

Downloading License File via Cybus Portal Website

Prerequisites

  • Valid username/password credentials for logging into the https://portal.cybus.io website

  • Your running Connectware instance that needs to be activated

  • A valid Connectware license key (this has to be the key that was used when the Connectware was installed)

Downloading License File

  1. To obtain a license file, log into portal.cybus.io with the username/password credentials provided in your activation email. If no such credentials have been issued to you yet, please contact sales@cybus.io so that we can get in contact with you.

  2. Click on the Licenses menu item, and click on the license you want to assign from your list of available licenses.

../_images/portal-license-detail.png

  1. In this License details page, you can download a license file but you must have your licensce key of that particular appliance available for input, too. Click on the Download License File icon in the upper right corner of the page.

../_images/portal-download-license-file.png

  1. Enter the license key of that particular appliance and press Download license file.

  2. Transfer the license file to the host machine running your Connectware instance.

Uploading License File into Connectware

To activate the license, you need to upload the obtained license file into your Connectware installation. The upload of the file can be performed by the Admin User Interface, or by accessing the REST endpoint using a command line client.

Using the Connectware Admin User Interface at Startup

Open a browser window for the Admin User interface. If the offline Connectware does not yet have a valid license file, the user interface will just show the activation dialog as shown below.

../_images/startup-nolicense.png

In this activation dialog, press the Upload License File button and upload the license file that has been downloaded as explained in the previous section.

After a quick refresh the license file has been uploaded and validated. Your Connectware is now ready for productive use.

Using the Connectware Admin User Interface after Startup

If you have uploaded a valid license file previously, but would like to update that file, navigate to System -> License, and press the Upload button in the top right.

../_images/license-upload-button.png

After a quick refresh the license file has been uploaded and validated. Your Connectware is now ready for productive use.

Using the REST endpoint with a command line client

To upload a license file directly from a shell environment you first need to install a data transfer client capable of communicating with REST endpoints. One such example tool is curl, to be used as follows:

curl -X PUT –insecure -u <USERNAME>:<PASSWORD> -d ‘payload=<LICENSE-FILE-CONTENT>’ https://<HOSTNAME>:443/api/system/licensefile

As can be seen in the example above you need to provide your user credentials (e.g. the admin username with suitable password) as well as the content of the license file as value of the property payload. The endpoint to upload the license file is located at https://<HOSTNAME>:443/api/system/licensefile .

Using the REST endpoint can be done both at first Startup or later to update the file.

Alternatively: You can inject the license file into an environment variable

To set up the license file using an environment variable you must configure the additional variable CYBUS_LICENSE_FILE in the service system-control-server. To do this you must define that environment variable with the contents of the license file you downloaded from the Portal, by using an API or by using the installer script’s download-license-file option.

The docker-compose.yml of your installation would be configured as follows:

# [...]
system-control-server:
environment:
   CYBUS_LICENSE_FILE: "Zm9vYmFyZm9vYmFyZm9vYmFyZm9vYmFyZm9vYmFyZm9v..."
   CYBUS_REGISTRY_PASS: ${CYBUS_REGISTRY_PASS}
   NODE_ENV: production
hostname: system-control-server
image: registry.cybus.io/cybus/system-control-server:1.0.58
# [...]