Concepts of the License Server

About server licenses

To start the server, a valid server license is required, which has to be installed first.

There are two options for licensing the MVTec License Server:

• Dongle-bound license for “On-Premises” installation
• “Cloud-Ready” license, bound to a cloud backend

Besides this, both variants are identical.

MVTec License Server On-Premises

This license is bound to a MVTec USB dongle and has a unique dongle ID.

If the dongle including a valid license is not present, the server does not start.
If the dongle is removed while the server is running, the server stops issuing new license sessions and revalidating existing sessions. As soon as the dongle is reattached, the server issues license sessions and revalidates them again.

MVTec License Server Cloud-Ready

This license does not have to be bound to any hardware. Instead, the server needs an active internet connection to validate the license online against a cloud backend (http(s)://wibu.cloud, SSL connection to port 443 is preferred).
If your firewall blocks access also from the inside, you must whitelist HTTP(S) connections to wibu.cloud and eu.wibu.cloud.

If the internet connection to the cloud backend is not available, the server cannot be started.
If the connection to the cloud backend is interrupted, the server still continues to work for a grace period of four hours. After the four hours, the License Server stops working (no new license sessions are issued and sessions are not revalidated). As soon as the connection to the backend is available again, the server resumes issuing license sessions.

About HALCON licenses

The HALCON license files (license*.dat) must be registered on the License Server and must also be available on the clients that want to request a license session from the server. To achieve the latter purpose, the license file contains an entry in the form server=https://<servername>:22022, which users can edit to specify the server.

To register license files with the License Server, you need to copy them to the configured license search path (see search_paths in config.yaml). By default, the license search path is the installation directory of the License Server (see below) and the subdirectory license below the installation directory.
At startup, the server loads all HALCON licenses (license*.dat) that are provided in the license search path as license files. During runtime, the server watches the configured search paths and adds any newly created or modified license files on the fly. You do not need to restart the server after adding or updating licenses.

The licenses must be issued for the server ID. For dongle-bound licenses, the ID is given by the MVTec USB dongle. For Cloud-Ready licenses, the ID is encoded in the extended protected data of the server license. The encoded ID is also added as name of the license.
A single license is always issued for a specific HALCON configuration, edition, and version and can restrict the allowed modules. Each license is uniquely identified by a UUID entry in the license file.
In case of license updates, the licenses contain the same UUID and only the newest license will be used. All older licenses with the same UUID are ignored.

About license sessions

When a HALCON application is started with a license file that references the server, HALCON requests a license session from the server. HALCON requests a license matching its edition (Steady or Progress), version, and required modules. The information about the edition and version are specific to the HALCON instance you are starting. The requested modules, however, are taken from the license file.

Serving licenses with different modules

A possible scenario is that the license server should serve licenses both with the Deep Learning module and licenses without the module. In this case, you want to make sure that only applications using deep learning features receive license sessions corresponding to a license containing the Deep Learning module.

To achieve this, use the HALCON licence file containing the Deep Learning module flag for applications using deep learning. Use the other license files for applications that do not use any deep learning features.

The License Server attempts to find a license that matches the request exactly. If no exact match is available, the server selects the next available valid “better” license according to the following criteria:

1. The License Server checks for a license with the same edition and version, but with more available modules than requested.
2. If no license is found, it includes licenses with a version that is newer than the requested version in the search.
3. If still no license can be found, it also includes Progress edition licenses if a Steady edition was requested (version 24.11 or newer only).

If a suitable license is found, the server returns a license session to HALCON and blocks the license for as long as the session exists. When HALCON stops and returns the license, or when the license server does not receive a revalidation request for a session within the configured interval, the session is terminated and the license is freed again.

If HALCON tries to revalidate an invalid session, it receives an error and must try to request a new license session.

About borrow licenses

The License Server supports borrowing licenses for offline usage. This feature allows users to borrow a license for a defined time period and use it on a machine without a network connection to the License Server.

Note

Borrowing licenses requires a license addon for the License Server. The addon is only available for “MVTec License Server Cloud-Ready”. Contact your distributor or MVTec Sales for details.

How borrowing works

Available licenses can be borrowed from the License Server for a specified time period of up to 7 days. The end time of the borrow period can be set to up to 6 weeks in the future. When a license is borrowed, the server generates a borrowed license file that is bound to a specific host ID (MAC address or Wibu Dongle ID). The borrowed license can then be used offline on the target machine without any connection to the License Server.

Once the borrow period expires, the license is automatically released and becomes available on the server again. The borrowed license file becomes invalid after the expiration time.

A borrowed license can not be returned. Once a license is borrowed, it remains unavailable on the server for the specified borrow period. However, it is possible to list all currently borrowed licenses and retrieve a borrowed license again.

Persistence of borrowed licenses

The License Server needs to securely persist information about which licenses are currently borrowed. For this purpose, the server generates a persistence file containing the relevant borrow information along with a signature file to ensure data integrity.

The location where the persistence files are stored can be configured (refer to Configuration). By default, the files are placed in the current working directory. This setting may need to be changed if the License Server was installed for all users and does not have write permissions in the installation folder.

Warning

If either the persistence file or the signature file is deleted or altered, the License Server will not be able to start. In this case, please contact MVTec to resolve the issue and restore the signature.

Interaction between sessions and borrowed licenses

Live sessions using licenses and borrowed licenses share the same license pool. You have to explicitly specify which licenses to borrow by referencing the license’s UUID.

When a license is borrowed, the license remains available for live sessions until the borrow period begins. If a session is started before the borrow period and is still running when the borrow period begins, the next revalidation of that session will fail. The application must then request a new license session, which will only succeed if another license is available. This also means that if all licenses are used in sessions and a license is borrowed, one of the sessions will fail upon the next revalidation.

Borrowing and active sessions

Consider a scenario where you have one license available, and it is borrowed for tomorrow from 8:00 to 20:00. Today, a HALCON application starts a session using that license. If the session is still active tomorrow at 8:00 when the borrow period begins, the next revalidation attempt will fail. The application will need to acquire a different license or wait until the borrow period ends.

Borrowing licenses

The License Server provides two ways to borrow licenses:

• Web Interface: A minimal web frontend is available at /ui/borrow for listing all available licenses and borrowing them for offline use.
• API: The Borrow API provides programmatic access to license borrowing functionality. See the API Reference for details on the JSON-RPC API.