.. _user/licensing: ##################### Connectware Licensing ##################### Your Cybus Connectware installation is running according to the enabled features and expiration duration as set in the `License`. .. _user/licensing/online-activation: 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 :ref:`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. .. figure:: ../resources/license/license-view.png :width: 750px 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. .. figure:: ../resources/license/license-refresh.png :width: 750px .. _user/licensing/offline-activation: 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: .. code-block:: shell ./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: .. code-block:: shell ./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. .. figure:: ../resources/portal-license-detail.png :width: 600px 3. 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. .. figure:: ../resources/portal-download-license-file.png :width: 600px 4. Enter the *license key* of that particular appliance and press *Download license file*. 5. Transfer the *license file* to the host machine running your Connectware instance. .. _user/licensing/offline-activation/upload: 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. .. figure:: ../resources/license/startup-nolicense.png :width: 600px 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. .. figure:: ../resources/license/license-upload-button.png :width: 600px 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 : -d 'payload=' https://: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://: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: .. code-block:: yaml # [...] 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 # [...]