.. _product-licensing-cli:

Product Licensing
-----------------

.. _21.4|VOSS-872|EKB-13096:
.. _21.4|VOSS-872|EKB-13050:

.. index:: license;license add file
.. index:: license;license add token
.. index:: license;license list
.. index:: license;license check
.. index:: voss;voss check-license



As part of the VOSS Automate 21.4 release, license enforcement will be enabled on all Automate deployments,
including production and lab environments. This will result in the requirement for license keys to be
obtained and installed on all platforms (within 7 days from the date of upgrade) to ensure no service
disruptions are experienced.


.. note::

   * For an overview of licensing and functionality 
     available in the GUI, refer to the Product License Management
     topic in the Core Feature Guide.

   * When a license has expired, GUI login is not available.
     Log in on the platform CLI and update a license as indicated
     below.

   * Customers can use an upgraded or installed platform for
     a grace period of 7 days in order to license the system.

    


.. rubric:: The Licensing Service


A license service is installed during installation/upgrade
from release 21.4 onwards.

Run ``app status`` to verify the presence and status
of the ``license-service`` application, for example:

::

   platform@VOSS:~$ app status
   selfservice v21.4.0 (2022-12-03 15:16)
      |-node                  running
   snmp v21.4.0 (2022-12-03 15:23)
      |-daemon                running (completed)
      |-traps                 running (completed)
   license-service v21.4.0 (2022-12-03 15:11)
      |-license-service       running
   cluster v21.4.0 (2022-12-03 15:21)
   template_runner v21.4.0 (2022-12-03 15:23)
   [...]


.. note::
  
   * An hourly schedule is run for VOSS Automate to process license service information.
   * The ``license-service`` cannot be stopped by running a command from the command line.


The CLI login screen also shows license information from 120 days before expiry.


The message levels are according to remaining number of days on the license, as follows:

* INFO: 90 < remaining days <= 120
* WARNING: 0 < remaining days <= 90
* ERROR: 0 >= remaining days

Refer to the Product License Management
topic in the Core Feature Guide for GUI Alerts intervals.

Otherwise, no information is displayed on login. 
The ``license list`` command can however be used to inspect the license
status. See: :ref:`health-report`.

.. note::

   * License commands and status messages are only available on:
       
     * unified nodes in a Unified Node Topology
     * application nodes in a Modular Cluster Topology




.. rubric:: Loading a License on the CLI


1. Obtain the license token from VOSS.
2. Log in on the platform CLI.
3. If required, the token can be copied to a file and uploaded to
   the ``/media`` directory. 

   Otherwise, have the token available in the copy buffer.

   a. If copied to a file, use the command below to add the token file
      - using the ``file`` parameter:

      ::

        license add file media/<token_file>
   
   b. If copied to the copy buffer, use the command below to paste the token
      - using the ``token`` parameter:

      ::

        license add token [<token string>]

   If a license token file is successfully added, the ``license check`` command
   is automatically run to process any changed licensing status or updated license token.
   Output example:

   ::

      Current license status "Licensed" remains unchanged. 
      Status was set on 2024-05-22T10:20:07
    


4. To process any changed licensing status or updated license token manually, use the command:
  
   ::
     
      license check
      
   (the equivalent command: ``voss check-license`` is also still available to ensure legacy support)

5. To view the currently loaded license token information, use the command:

   ::

      license list



.. rubric:: Check License Details


At any stage, the details of license tokens can be viewed.


* Use the ``license list`` command, for example:


::

   platform@VOSS:~$ license list
       6009914029c384002787ef2e: 
           Audience: Automate
           Expired: false
           Expiry: 2022-11-07T10:20:09Z
           Platform Description: N/A
           Token ID: d2ba2d70-fc84-47af-a57e-5cb9c39878d8
  

.. rubric:: Refresh License


A command is available to verify a VOSS Automate license status,
for example, after updating the license token.

The command: ``voss check-license`` uses the running ``license-service`` application information
to refresh the license information of the VOSS Automate deployment.

For example, if the command is run from the CLI:

::

   platform@VOSS:~$ voss check-license
   Current license status "Licensed" remains unchanged. 
   Status was set on 2022-11-01T13:46:07

then the time of that command will update the **License Last Checked** time stamp
on the **Manage License** GUI form (accessible by the ``sysadmin`` user) to that time.
In this example, the system was already licensed and this check reflects this license status
as "unchanged".


.. rubric:: Renewing a License


When a license has expired, contact VOSS to renew the license.
Provide the platform ID (UUID) which is shown when running ``license list``.