.. _licensing-principles:

*************************************
Licensing
*************************************

.. rubric:: In this chapter:

.. contents::
   :local:


Licensing Principles
==========================

The FindFace Server licensing is granted using the following criteria:

#. ``extraction-api`` licensing.

   * Features:

      * Body: bags, body mideast clothes types, phone use, pose (position of a body) protective equipment, body emben, uniform, other attributes;
      * Car (vehicle): categories, description, dumptruck types, license plate, license plate visibility, orientation, car emben, special types, trash truck, weight types, other attributes;
      * Face: gender, glasses, hair, headpose, headwear, highlight, liveness, luminance uniformity, medmask, mouth attributes (occlusion, openness, smile), scars, tatoo;
      * Head: motohelmet;
      * Other: camera tampering, container number, crowd, dumpster types, fast index, garbage types, merchandise emben, pet face emben, planter damage, recording, road sign damage, snow on road, street light working, trash bin fill.

   * ``extapi`` limit: the total performance of the ``extraction-api`` available to a user. This limit is applied by either restricting the number of ``extraction-api`` processes (which corresponds to video cards for GPU usage) or the maximum CPU core count utilized by a single extractor (based on the ``max_batch_size`` parameter for CPU processing).

#. ``tntapi`` licensing.

   * ``objects_tntapi`` limit: the total number of objects stored in all currently running ``tntapi`` instances is licensed.
   * ``tntapi_fast_index`` feature: this feature is required for enabling the ``tntapi`` :ref:`fast index / live index <fast-index>`.

#. ``video-worker`` licensing.

   * ``cameras_*`` limits: restrict the number of concurrently active streams within the ``video-worker`` that are processing detections of specific object types. For example, the ``cameras_face`` limit restricts the number of streams performing face object detection.
   * ``cameras_video_recording`` limit: limits the number of simultaneously active video recording streams in the ``video-worker`` for use with ``video-storage`` / ``video-streamer``. The parameter for configuring jobs is ``enable_recorder``. See :ref:`Video Object Detection <video-config>`.
   * ``face_liveness`` feature: allows the use of liveness verification at the ``video-worker`` level (the same feature as in the ``extraction-api``), the ``enable_liveness`` parameter. See :ref:`Video Object Detection <video-config>`.
   * ``*_action_*`` feature: allows the use of appropriate BNCHW-models, e.g. base actions (walk, run, stand, ride, sit), car (vehicle) interactions (getting in or out the vehicle).

You can choose between the following licensing methods:

* The online licensing is provided by interaction with the NtechLab Global License Manager ``license.ntechlab.com`` and requires a stable internet connection, DNS, and open port 443 TCP. Upon being disconnected from the internet, the system will continue working off-grid for 4 hours.

.. note::
   It is possible to prolongate the off-grid period for up to 2 days. Inform your manager if you need that.

* The offline licensing via a USB dongle requires a USB port on the physical server with the ``ntls`` service.
* The Sentinel offline software licensing via hardware fingerprint requires Sentinel drivers installed on the physical server with the ``ntls`` service.
* The Guardant offline software licensing via hardware fingerprint requires Guardant Control Center installed on the physical server with the ``ntls`` service.

.. important::
   For the system to function, a single instance of ``ntls`` should be enough. If your system requires more license servers, contact your NtechLab manager beforehand to prevent your system from being blocked.

.. _upload-license:

View and Update License
================================

After installing FindFace Server, upload the license file you obtained from the manager into the system. Use ``ntls`` web interface ``http://<NTLS_IP_address>:3185``.

    |license_en|

     .. |license_en| image:: /_static/license_en.png
        :scale: 70%

     .. |license_ru| image:: /_static/license_ru.png
        :scale: 70%

Use :guilabel:`General`, :guilabel:`Licenses`, :guilabel:`Intervals`, :guilabel:`Services` tabs to consult current licensing information and upgrade your license.


.. _grd:

Offline Licensing via USB dongle
=======================================

To implement the licensing via a USB dongle, do the following:

#. Inform your manager that you intend to apply this licensing method and request your USB dongle and a license file.

#. Create a new **udev** rule.

   #. Download the :download:`95-grdnt.rules <_scripts/95-grdnt.rules>` file (e.g., into the ``/home/username/tmp/`` directory).

   #. Copy the ``95-grdnt.rules`` file into the ``/etc/udev/rules.d/`` directory.

      .. code::

         sudo cp /home/username/tmp/95-grdnt.rules /etc/udev/rules.d/

#. Reload udev rules.

   .. code::

      udevadm control --reload
      udevadm trigger

#. Make sure the system has a device named ``grdhid0``.

   .. code::

      /dev/grdhid0

#. Mount the ``/dev/grdhid0`` device into the ``ntls`` container by using volume option at runtime with the ``docker run`` command.

   .. code::

      -v /dev/grdhid0:/dev/grdhid0


.. _sentinel:

Sentinel Offline Software Licensing via Hardware Fingerprint
=====================================================================

.. note::
   Sentinel is a type of offline licenses that do not require any physical media for its work.

   Glossary:

   * Sentinel is a software protection and licensing system by `Thales <https://cpl.thalesgroup.com/>`_. It allows you to implement offline licensing without access to a global server.
   * The C2V file is a file, containing data about a hardware fingerprint of the client’s machine, for binding the license only to this machine. This file is generated by the sentinel library. The C2V file is generated on the client’s machine where the license key will be installed later.

To implement the Sentinel fingerprint licensing, do the following:

#. Inform your manager that you intend to apply this licensing method and request your unique license id. The manager will also supply you with the ``sentinel-lib_*.deb`` package necessary for the FindFace Server and Sentinel integration.
#. Install the Sentinel drivers on the physical server with the ``ntls`` component.

   Do the following:

      #. Download `Sentinel drivers <https://supportportal.gemalto.com/csm?id=kb_article_view&sysparm_article=KB0018315#>`_ from the official website.

      #. Unzip the downloaded archive and browse to it.

         .. code::

            tar -xvzf Sentinel_LDK_Linux_Runtime_Installer_script.tar.gz
            cd Sentinel_LDK_Linux_Runtime_Installer_script/

      #. There is another archive ``aksusbd-9.15.tar.gz`` inside the archive. Unzip it and browse to the resulting directory.

         .. code::

            tar -xvzf aksusbd-9.15.tar.gz
            cd aksusbd-9.15/

      #. Run the installation command.

         .. code::

            sudo ./dinst

      #. Run and check the statuses of the Sentinel services.

         .. code::

            sudo systemctl start aksusbd.service hasplmd.service
            sudo systemctl status aksusbd.service hasplmd.service

#. Mount the ``/var/hasplm`` and ``/etc/hasplm`` directories into the ``ntls`` container. To do so, use ``-v`` option at runtime with the ``docker run`` command.

   .. code::

      -v /var/hasplm:/var/hasplm -v /etc/hasplm:/etc/hasplm

#. ``ntls`` must be running in the host's network namespace.

   .. code::

      --net=host

#. Put the ``sentinel-lib_*.deb`` package received from your manager into some directory on the same host. Install the package.

   .. code::

      sudo dpkg -i /path/to/sentinel-lib_*.deb

#. Take a hardware fingerprint (C2V file) by sending the following API request to ``ntls``.

   .. code::

      wget <NTLS_IP_address>:3185/c2v -o sentinel.c2v


#. Send the License ID and the C2V file to your manager and receive your license file in return.
#. Upload the license file on the web interface ``http://<NTLS_IP_address>:3185``.


.. _grd_software:

Guardant Offline Software Licensing via Hardware Fingerprint
===============================================================

.. note::
   This type of license is similar to Sentinel offline software licenses, but requires the Guardant service to function instead of Sentinel services.

To implement the Guardant fingerprint licensing, follow these steps:

#. Inform your manager that you intend to use this licensing method and request your unique license id.

#. Install the Guardant Control Center on the physical server with the ``ntls`` component.

   Do the following:

      #. Download `Guardant Control Center <https://www.guardant.ru/support/users/control-center/>`_ from the official website.  For Ubuntu/Debian, download the ``grdcontrol*.deb`` package. The most recent version that has been tested with is 3.27. Use later versions of Guardant Control Center, if any, at your own discretion.

      #. Install it. E.g., if you are running Ubuntu, execute:

         .. code::

            sudo dpkg -i /path/to/grdcontrol*.deb

      #. Make sure that the Guardant Control Center is up and running.
         On Ubuntu 22.04, you can do this as follows:


         .. code::

            sudo systemctl enable grdcontrol --now
            sudo systemctl status grdcontrol


#. ``ntls`` must be running in the host's network namespace.

   .. code::

      --net=host

#. Take a hardware fingerprint (C2V file) by sending the following API request to ``ntls``.

   .. code::

      wget <NTLS_IP_address>:3185/c2v/guardant -o guardant.c2v

   .. warning::
      Be aware that Sentinel c2v is not compatible with Guardant c2v and vice versa.

   .. note::
      You can also download c2v using the ``ntls`` web interface.

#. Send the License ID and the C2V file to your manager and receive your license file in return.
#. Upload the license file on the web interface ``http://<NTLS_IP_address>:3185``.