Skip to end of metadata
Go to start of metadata

Icon

This document assumes you're familiar with the Labs64 NetLicensing service. If you need more info about NetLicensing, please visit https://netlicensing.io.

Motivation

NetLicensing recommended operation mode is online validation. This mode has many advantages:

  • Security: licensing assets are stored in a secure cloud database, licensee has no direct access to the assets
  • Traceability: license usage information is always up to date and available at any time
  • Flexibility: licensing assets can be adjusted by vendor at any time with immediate effect

Nevertheless, in some environments access to the NetLicensing cloud services is not possible for technical or organizational reasons, such as no internet connectivity or security restrictions. To enable NetLicensing functionality even in such restricted environments, we offer NetLicensing Agent - a standalone module, that is able to operate without connectivity to the NetLicensing cloud services and responding in a local network or on a local host to the validation requests same as the NetLicensing cloud service does.

Legal Information

Please read:

NetLicensing Agent

NetLicensing Agent is a software component of Labs64 NetLicensing service. Agent runs on a local server and responds to the validation requests in place of NetLicensing, allowing operation in isolated networks without connection to the Internet and the NetLicensing cloud service.

NetLicensing Agent is a simple java command-line tool that only requires JRE for its operation.

Files

FileDescription
netlicensing-agent-<version>.jar

Java executable. This is the only downloadable for the NetLicensing Agent. In addition you'll need Java 8 Runtime (JRE). During execution Agent creates a local database in the 'database/' subdirectory of the directory, from where it is executed (working directory). Ensure to execute the Agent always from the same working directory, so it finds its database files.

database/*Database files. Created and maintained by the agent. You may want to include this directory in a backup of the host running the agent. It is recommended to stop the agent when creating a backup copy / snapshot of the database files to ensure backup integrity.
{n}_netlicensing-assets.xmlFile(s) with exported assets. Created by the agent. Contain sensitive information, care to be taken when copying / transferring these files.

Command Line

Syntax:

OptionDescription
--helpPrints short help on the console and exits.
--action=<action>See modes of operation.
--nlic.username=<username>

Your username for accessing NetLicensing cloud service.

--nlic.password=<password>

Your password for accessing NetLicensing cloud service.

--port=<port>Port the agent will listen on. Default is 8080.
--licensees=<licensees>
Licensee(s) numbers filter for assets exporting (comma-separated list) 

Modes of Operation

Agent runs in different modes depending on the requested 'action':

ActionMode description
export-assets
Downloads assets from the NetLicensing cloud service and saves it to a local file. This file should be transferred together with the agent executable to the disconnected environment for offline operation.
import-assets
Import assets from the local file (created with 'export-assets') to the local database. This is a preparation step for the offline operation mode.
run-agent-offline
Offline server mode, NetLicensing Agent runs as local server and responds to 'validate' calls from clients same as the main NetLicensing service.
run-agent

Runs as a caching proxy, connecting to the NetLicensing cloud service if available, and responding with the last known state when connectivity is not available. This mode is meant for the environments that may have only occasional or unstable connection to the internet.

(warning) Currently this mode has limited support and should not be used in production environment.

 

Setting Up for the Offline Mode

  1. Prepare licensing assets same way as you would do for normal NetLicensing operation as a cloud service.

  2. Download NetLicensing Agent
  3. On a workstation having connection to the NetLicensing cloud service (internet connection) execute Agent with 'export-assets' action to export assets from the NetLicensing cloud service to the local file.

    Upon execution the agent will create one or more files with the name '{n}_netlicensing-assets.xml' in the current working directory, where {n} is a sequential number. You can safely ignore / delete the 'database/' subdirectory after execution of this step.

  4. Transfer created file(s) with the exported assets and the NetLicensing Agent executable jar to the target disconnected environment, and install on the target server in the working directory of your choice (pay attention to the security!). Ensure proper JRE is configured on the target server.

  5. Execute Agent with 'import-assets' action, while in the working directory.

    Local database will be created in the 'database/' subdirectory and licensing assets will be imported from the transferred files. After successful execution, the export files '{n}_netlicensing-assets.xml' can be removed. Ensure not to delete / alter the 'database/' subdirectory and its content!

  6. Start Agent with 'run-agent-offline' action.

    With this action the agent will keep running and listening on the specified port until stopped by SIGINT (Ctrl-C). Make sure firewall, if any, allows this connection.

Using Agent in Caching Proxy Mode

  1. Download NetLicensing Agent
  2. Start the agent with 'run-agent' action.

  3. Agent will listen on localhost port 8080, accepting validate requests and forwarding it to the NetLicensing cloud service at: https://go.netlicensing.io

  4. In this mode Agent only responds to validate requests, any other API requests should be sent directly to the NetLicensing cloud service. Accordingly, integration in your product should send validate requests to the host running Agent, while other API requests, if needed, should be sent to the NetLicensing cloud service.

 

Important notes

Icon
  • Validate requests with different arguments are treated as distinct validations and cached separately.
  • Validate requests that involve licensing model parameters modifying licenses state are not supported (e.g. Floating license check in / check out).
  • For the first validate request execution with unique set of arguments, Agent must have a connectivity to the NetLicensing cloud service. Subsequent validate requests with the same arguments can be successfully executed by Agent within the "ttl" period, also when connectivity to the NetLicensing cloud service is not available.
  • Cache is not persisted across agent restarts (in-memory storage).

 

Client Configuration

Client should be configured to point to the local server running NetLicensing Agent (port 8080 by default) instead of main NetLicensing service, i.e. API base URL changes from:

to:

NetLicensing Agent will respond to the validation requests. Parameters have the same format as described in the NetLicensing API.

Known Limitations

Licensing Models

NetLicensing Agent v2.3.9 only supports full assets import. In case licenses are updated on the NetLicensing server (master copy), new import to the Agent database is required to reflect these changes, which will erase any state changes that have happened on the Agent since the previous import. This has implications on the logic of some Licensing Models, as summarized below.

Licensing ModelDeviation from the model logic if assets import repeatedRecommendation
Try & BuyTrial period may start over, however if perpetual license purchased in the mean time, the model will keep functioning properly.

Option 1: To mitigate the problem with the trial period starting over, set the trial license startDate explicitly before performing the export.

Option 2: Only update if perpetual license was purchased after initial export.

SubscriptionLicenses having initially no startDate set will lose any startDate that was set during agent operation. This may lead to increased subscription period after import.Ensure startDate is set explicitly before performing the export.
RentalSee Subscription.See Subscription.
FloatingAll sessions will be treated by the server as checked in, making possible to run higher number of sessions for up to maxCheckoutValidity time period after fresh import.
  • Keep maxCheckoutValidity short enough to minimize the impact.
  • In case increased number of simultaneous session should be avoided by all means, keep agent shut down for maxCheckoutValidity period upon new import to let existing sessions expire.
Multi-FeatureNo deviation-
Pay-per-UseAll used quantitiy values will be lost.Avoid using this model with the Agent v2.3.9.
QuotaNo deviation-

Security

Virtual Environments

In today's virtualized environments it is very easy to create and clone virtual machines, which allows to create exact copy of a NetLicensing Agent instance including all licensing assets, if installed in a virtual machine. Also having export file and the agent executable it is possible to create unlimited number of agent instances with the same set of assets. This issue will be addressed in the future agent releases, for the moment we recommend a controlled installation of NetLicensing Agent at customer premises on a host properly protected against tampering using up-to-date HW/SW security measures.

Networking

NetLicensing Agent by itself do not provide any security for the communication with the client. This opens the door for possible mangling of the responses sent by the agent. To eliminate this risk, in addition to controlled installation of the agent on a secured host we recommend to setup agent behind HTTPS reverse proxy. Reverse proxy and SSL support is available as a standard functionality in most popular HTTP frontends Apache, NGINX and IIS. Soon we will publish guidelines how to configure HTTP frontend - stay tuned.

Licensee Auto-Create

Agent does not support licensee auto-create.

See also

  • No labels