Link
Search
✎

NetLicensing Agent

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.

(warning) NetLicensing Agent is only available in selected pricing plans. In case your pricing plan does not include NetLicensing Agent, you’ll get the message:

Payment required. Feature "NetLicensing Agent" is not allowed. Please upgrade your plan.

Files

File Description
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/*

.assets

 Database files. Created and maintained by the agent. You may want to include this 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.xml File(s) with exported assets. Created by the agent. Contain sensitive information, care to be taken when copying / transferring these files.

Command Line

Syntax:

java -jar netlicensing-agent.jar --help
java -jar netlicensing-agent.jar --version
java -jar netlicensing-agent.jar --action=<action> [options]

Command line options:

Option Long option Default value

Description

 
-h
 
--help
  

Print help screen and exit.

 
-v
 
--version
  

Print the version of the application and exit.

 
-a
 
--action
  

Action to perform. Available actions:

  • run-agent - run as a caching proxy to the NetLicensing Cloud;

  • run-agent-offline - run in offline mode, using assets from the local database;

  • export-assets
    - export assets from the NetLicensing Cloud to the local file(s);

  • import-assets
    - import assets to the local database from the local file(s) created with export-assets.
  
--core.base.host
 
https://go.netlicensing.io

NetLicensing Cloud host, including protocol and port, if necessary. Used for export-assets.

 
-u
 
--nlic.username
  

Vendor username at NetLicensing Cloud. Required for export-assets.

 
-p
 
--nlic.password
  

Vendor password at NetLicensing Cloud. Required for export-assets.
 

--port

 
8080

TCP port the NetLicensing Agent will listen on. Used for run-agent and run-agent-offline.

 
-o
 
--output
 .

Local directory where output files of export-assets to be saved.

 
-i
 
--input
 .

Input files for import-assets to be read from this local directory.

 
-l
 
--licensees
  

Comma-separated list of licensee numbers targeted for export-assets. Required for export-assets.

 
-f
 
--force
  

Ignore conflicts on export-assets or import-assets.
 

--serial-number

  

Specify smart card serial number for export-assets. Required for export-assets, unless --without-card is used.
 

--without-card

  

Don't use the smart card. Can be used for export-assets, import-assets, run-agent-offline.
 

--verbose

  

Enable detailed log output to the console.

Modes of Operation

Agent runs in different modes depending on the requested ‘action’:

Action Mode 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 main NetLicensing 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.

Note:
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, note serial number of the smart card (provided with smart card).

  3. On a workstation having Internet connection with access to the NetLicensing Cloud, execute Agent to export assets from the NetLicensing Cloud to the local file:

    java -jar netlicensing-agent.jar --action=export-assets --nlic.username=<username> --nlic.password=<password> --licensees=<licensee>[,...] --serial-number=<serial number>

    Agent binds exported licensees to the smart card with provided serial number, and creates one or more transfer files with the name ‘{n}_netlicensing-assets.xml’ in the current working directory, where {n} is a sequential number. Smart card must not be present at this step, however in case you plan to work without smart card, add ‘--without-card’ option, see also note below.

  4. Transfer files created at step 3 and the NetLicensing Agent executable jar to the target disconnected environment. Save on the target server in a working directory of your choice, take care of access security for the directory! Ensure Java 8 JRE is configured on the target server.

  5. Execute Agent with ‘import-assets’ action, while in the working directory. (warning) Requires smart card (see note below).

    java -jar netlicensing-agent.jar --action=import-assets

    Agent creates local database in the working directory, and imports assets from the transfer files into the new database. After successful execution, the transfer files ‘{n}_netlicensing-assets.xml‘ can be removed. Do not delete or alter the content of the created files belonging to the local database!

  6. Staying in the same working directory as in step 5, start Agent to serve offline. (warning) Requires smart card (see note below).

    java -jar netlicensing-agent.jar --action=run-agent-offline --port=8080

    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. Also read the article Securing the Agent with SSL/TLS.

Requires smart card

If using smart card, be sure it is attached, see also Preparing to work with smart card. If working without smart card, use --without-card option.

Steps 3-5 can be repeated to update licensing assets after changes have been made on the NetLicensing Cloud.

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:

https://go.netlicensing.io/core/v2/rest/...

to:

http://yourhost:8080/rest/...

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

Security

Execution Environment

Having export file and the agent executable it is possible to create unlimited number of agent instances with the same set of assets. Besides, today’s virtualized environments allow easy cloning of virtual machines, which allows to create exact copy of a NetLicensing Agent instance including all licensing assets even without having an export file. This risk can be significantly reduced by a controlled installation of NetLicensing Agent at customer premises on a host properly protected against tampering using up-to-date HW/SW security measures, including secure networking (see below). 

Smart Card

In some cases fully controlled installation of NetLicensing Agent is not possible, or it is desired to install Agent in a virtual environment, in which case user gets access to the NetLicening Agent executable / database files. To keep security even in these cases, NetLicensing Agent offers protection with smart card. Smart card protects from the Agent cloning, as well as from attempts to revert the use counters / time accounting by restoring the environment from an older snapshot. Note that the communication security (see below) is still important, therefore we recommend a controlled installation even when using the smart card.

Networking

NetLicensing Agent by itself do not provide any security for the communication with the client. This leaves the possibility of mangling the responses sent by the agent. To eliminate this risk, in addition to controlled installation of the agent on a secured host and/or using smart card security 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. Please refer to Securing the Agent with SSL/TLS for details.

Known Limitations

Licensing Models

On repeated export/import operation for the assets, NetLicensing Agent performs merging of changes made in the NetLicensing Cloud (master copy) into the current state of the Agent local database to ensure Agent functioning as close as possible to the NetLicensing Cloud. Nevertheless, the logic of some Licensing Models in Agent may differ from that of the NetLicensing Cloud, as summarized below.

Licensing Model Deviation from the model logic if assets import repeated Recommendation
Try & Buy Trial 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.
Subscription Licenses 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.
Rental See Subscription. See Subscription.
Floating All 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-Feature No deviation -
Pay-per-Use All used quantity values will be lost. Avoid using this model with the current Agent release.
Quota No deviation -

Entity Numbers

Although NetLicensing Cloud allows to use almost any character in entity numbers, do not use the following characters for entities exported to NetLicensing Agent, as it will conflict with export/import procedures:

  • comma - ,
  • semicolon - ;

Licensee Auto-Create

NetLicensing Agent does not support licensee auto-create.

Table of contents