Click to go to home page

Setup, Management And Deployment Guide


Preface

Overview Of Setup, Management And Deployment Activities

Installing Your Product

Product Directory Tree

Files

Subdirectories

Running The License Manager

All Platforms Including Windows

Windows Only

First Time Execution

Every Execution

Running The License Management Command Line Utilities

Setup For Programmatic Key Generation

Managing Your EasyLicenser Product License

Backing Up And Restoring Your License Database State

Deactivating Your EasyLicenser Installation

Uninstalling EasyLicenser

Deploying The EasyLicenser Run Time Library With Your Applications

Java on all platforms

C/C++ on all platforms

Impact Of Run Time Library On ISV Product Installation

Java

C/C++ on all platforms

Deploying The EasyLicenser Redistribution Tools To Your End Customers

Next Steps


Preface

The purpose of this document is to describe how to set up and manage an EasyLicenser product installation, and how to deploy the EasyLicenser run time libraries with your applications.

Overview Of Setup, Management And Deployment Activities

The activities encompass:

1.      Downloading and installing the product.

2.      Running EasyLicenser.

3.      Managing the EasyLicenser product license.

4.      Backing up and restoring the state of your configuration and databases.

5.      Deploying the run time library distribution for use by your applications.

Installing Your Product

Installation is a two-step process:

1.      Download the product zip file.

Select a download directory and download EasyLicenser as a platform-neutral zip file named ezlicmgreval.zip. Depending on the origin of your download, the file name may vary.

If you have an existing product installation based on EasyLicenser 1.1 or above, you can perform an upgrade as follows:

1. Position to the existing product installation root directory (inside ezlic2.5).

2. Download ezlicmgrupgrd.zip from the Agilis download site or the URL provided to you by Agilis.

2.      Unzip the file.

Select an installation directory and unzip the file using any of the standard Zip-compatible utilities, such as Winzip (7.0 or above) on Windows or the unzip command available on most Unix / Linux systems, or (if a JDK is installed) the jar utility included with the JDK on any platform.  For example, on Unix:

$ cd ~/myproductsrootdir

$ unzip $DOWNLOADDIR/ezlicmgreval.zip

A ezlic2.5 subdirectory will be created, under which the product directory tree is created.  The structure and contents of the product directory tree are described below under Product Directory Tree.

After installation and before using the product, be sure to read the release notes and late-breaking information in file README-EZLM25-mmddyy located at the product home directory.

Provided your installation is recharged with EasyLicenser keys at a version level 2.5 or higher, you may install and activate any number of copies of EasyLicenser on a machine. With older key versions, you may install and activate at most one copy of EasyLicenser on a given host account, and if you wish to subsequently perform an installation on a different directory on the same host account, you will need to first deactivate the prior installation after backing up its data. For details on deactivation, see the License Manager User Guide.

If you are performing an upgrade, instead unzip the ezlicmgrupgrd.zip file downloaded as described above, and unzip it while positioned under the existing product installation root directory.

Product Directory Tree

The product root directory is the ezlic2.5 directory that is created when the product distribution zip file is unzipped.  Files in the directory tree should never be directly viewed or manipulated unless otherwise specified.

The directory tree is organized as follows:

Files

The files under the root directory include the EasyLicenser license configuration files, executable jar files for the license manager user interface as well as command line tools and utilities, the associated Unix shell and DOS command files, and the readme file. A command line tool's shell or DOS script invokes the corresponding executable jar file, and assumes that the java java virtual machine executable program is accessible from the PATH environment variable.

ezconfig

This is the configuration file that manages and tracks the state of your specific EasyLicenser product installation. It is important that you do not edit, delete, replace or relocate this file, otherwise EasyLicenser will cease to function.

ezlicmgr25.jar

This is the license manager console executable jar file that is invoked as described below under Running The License Manager.

ezlicmgrclonekey25.jar

This is the clone license key command line utility executable jar file that is invoked as described below under Running The Command Line Utilities.

ezlicmgrdeact25.jar

This is the deactivate configuration command line utility executable jar file that is invoked as described below under Running The Command Line Utilities.

ezlicmgrdmp25.jar

This is the dump configuration command line utility executable jar file that is invoked as described below under Running The Command Line Utilities.

ezlicmgrgenkey25.jar

This is the generate key command line utility executable jar file that is invoked as described below under Running The Command Line Utilities.

ezlicmgrimp25.jar

This is the import command line utility executable jar file that is invoked as described below under Running The Command Line Utilities.

ezlicmgrkeyinfo25.jar

This is the get license key info command line utility executable jar file that is invoked as described below under Running The Command Line Utilities.

ezlicmgrmcinfo25.jar

This is the get machine info command line utility executable jar file that is invoked as described below under Running The Command Line Utilities.

ezlicmgrrecharge25.jar

This is the recharge command line utility executable jar file that is invoked as described below under Running The Command Line Utilities.

ezlicmgr.bat, ezlicmgr.sh

These are the Windows and Unix command files respectively for launching the License Manager UI ezlicmgr25.jar executable jar from a command window or shell script.

ezlicmgrclonekey.bat, ezlicmgrclonekey.sh

These are the Windows and Unix command files respectively for launching the command-line license key cloning utility's ezlicmgrcmd25.jar executable jar from a command window or shell script.

ezlicmgrdeact.bat, ezlicmgrdeact.sh

These are the Windows and Unix command files respectively for launching the command line deactivation utility's ezlicmgrdeact25.jar executable jar from a command window or shell script.

ezlicmgrdmp.bat, ezlicmgrdmp.sh

These are the Windows and Unix command files respectively for launching the command line dump-configuration utility's ezlicmgrdmp25.jar executable jar from a command window or shell script.

ezlicmgrgenkey.bat, ezlicmgrgenkey.sh

These are the Windows and Unix command files respectively for launching the command line key generation utility's ezlicmgrgenkey25.jar executable jar from a command window or shell script.

ezlicmgrimp.bat, ezlicmgrimp.sh

These are the Windows and Unix command files respectively for launching the command line import utility's ezlicmgrimp25.jar executable jar from a command window or shell script.

ezlicmgrkeyinfo.bat, ezlicmgrkeyinfo.sh

These are the Windows and Unix command files respectively for launching the command line license key information retrieval utility's ezlicmgrkeyinfo25.jar executable jar from a command window or shell script.

ezlicmgrmcinfo.bat, ezlicmgrmcinfo.sh

These are the Windows and Unix command files respectively for launching the command line machine information retrieval utility's ezlicmgrmcinfo25.jar executable jar from a command window or shell script.

ezlicmgrrecharge.bat, ezlicmgrrecharge.sh

These are the Windows and Unix command files respectively for launching the command line license recharge utility's ezlicmgrrecharge25.jar executable jar from a command window or shell script.

ezlmredist25.zip

This is a zip file that is intended for redistribution to end customers. It contains the necessary files for collecting node locking information, running diagnostics, and other tasks for simplifying the operations aspect of license key management by your end customer. The zip file currently packages ezlmgetmcinfo for generating node locking information (for both Java and C/C++ applications) and sysinfo for introspecting the Java runtime environment (for Java applications). Over time, additional end customer oriented tools and utilities will be included in this package.

README-EZLM25-mmddyy.TXT

This text file is viewable with any text editor.  The file contains release notes and late breaking information that are not included in the product documentation.  You should read the contents of this file before starting to use the product.

Subdirectories

backup

This is the default directory that is presented to you when you use the License Manager to perform system backups and restores.  It is recommended that you not use this subdirectory and instead explicitly specify a backup directory on a different hard disk, preferably located on a different machine on the network, in order to protect your installation from media failures.

cpp

The directory contains the C/C++ run time library header files, libraries and sample application code. It is used by your C/C++ application developer and also contains the run time libraries that you embed into your applications.

Each subdirectory that contains binary files is organized into a series of platform specific subdirectories. The main product distribution includes subdirectories for all currently supported platforms, which are 32-bit and 64-bit Windows, 32-bit and 64-bit Linux-Intel, 32-bit and 64-bit Solaris on SPARC and Intel, and Mac OS X universal binaries, named win32, win64, linux-intel-redhat, linux-intel64-redhat, linux-intel-suse, linux-intel64-suse, linux-intel-ubuntu, linux-intel64-ubuntu, sun-gnu, sun64-gnu, sun-intel-gnu, sun-intel64-gnu and macosx-ubi respectively. C++ support for additional platforms may also be available in a separate download file from the download page at the EasyLicenser web site or otherwise provided to you by Agilis. For a complete specification of the C/C++ support, please refer to C/C++ Runtime Library Platform Specifications.

demo

The directory contains source and binary code for demo applications.

bin/platform

Each platform-specific subdirectory contains binary code for the demo applications.

C_Demo.exe / C_Demo

This is the executable code for a simple Hello World C demo program that checks a given list of license keys for validity against a given user / host name. If the key is valid, it is decomposed and its parameters are displayed. Otherwise, an error message is displayed.

The program illustrates how to use the C API's to perform simple license key checks.

To see how to run the program, type C_Demo / C_Demo.exe with no arguments. The program expects up to four arguments: the name of a text file that contains a license key to check, the user / host name that allegedly matches what is in the key, and optionally (if inputting keys generated for password-protected products) a product name and an application password's public key. The text file may be in any of the license key export or publish formats supported by EasyLicenser.

C_Demosl.exe / C_Demosl

This is a version of C_Demo / C_Demo.exe that is built with a static link against the static library version of the C/C++ EasyLicenser runtime library.

cdemoextapi.exe / cdemoextapi

The executable code for a C demo program illustrates use of the extended API's for deferred-mode licensing and automatic metering. The program is invoked multiple times, initially in activation mode, then in license checking mode, and finally in deactivation mode. The docdemoextapi.bat / docdemoextapi.sh command batch command file encapsulates the multiple invocations for convenience and also illustrates parameter usage.

To see how to run the program, type cdemoextapi.exe / cdemoextapi with no arguments. The program expects up to eight arguments: a command indicating activation / check / deactivation, the name of a text file that contains a license key to activate, a product name and corresponding application password's public key, the user / host name that allegedly matches what is in the key, an optional auxiliary key for enabling deferred-mode licensing, an optional "used-quota increment" value representing quota consumption, and optionally an explicit hidden file directory specification. The text file for the license key may be in any of the license key export or publish formats supported by EasyLicenser. The text file for the auxiliary key is in raw key format.

cdemosecure.exe / cdemosecure

The executable code for a C++ demo program illustrates how to use EasyLicenser's anti-spoofing security mechanisms. The program makes use of the secure license key check and key cookie API's, digital signature checking, and custom key handlers. The program checks a given license key for validity against a given user / host name and also manages and checks for the current metered consumption in persistent store.

To see how to run the program, type cdemosecure.exe / cdemosecure with no arguments. The program expects up to five arguments: the name of a text file that contains a license key to check, the user / host name that allegedly matches what is in the key, the name of a text file containing the signature of the EasyLicenser run time library, and optionally (if inputting keys generated for password-protected products) a product name and an application password's public key. The text file may be in any of the license key export or publish formats supported by EasyLicenser.

cdemostate.exe / cdemostate

The executable code for a C demo program illustrates secure state management using the secure license key check and key cookie API's. The program checks a given license key for validity against a given user / host name and also manages and checks for the current metered consumption in persistent store. The program is invoked multiple times. The docdemostate.bat / docdemostate.sh command batch command file encapsulates the multiple invocations for convenience and also illustrates parameter usage.

To see how to run the program, type cdemostate.exe / cdemostate with no arguments. The program expects up to five arguments: the name of a text file that contains a license key to check, the user / host name that allegedly matches what is in the key, a "used-quota increment" value representing quota consumption, and optionally (if inputting keys generated for password-protected products) a product name and an application password's public key. The text file may be in any of the license key export or publish formats supported by EasyLicenser.

docdemoextapi.bat / docdemoextapi.sh

The command file that performs multiple invocations of cdemoextapi.exe / cdemoextapi to illustrate the cycle of activation, license checking, and deactivation.

docdemostate.bat / docdemostate.sh

The command file that performs multiple invocations of cdemostate.exe / cdemostate to illustrate state management.

In order to be able to run the versions of the programs that link with the dynamic library version of the EasyLicenser runtime library, it is necessary to meet the prerequisite of including the appropriate platform-specific subdirectory under the cpp/lib directory in your PATH / LD_LIBRARY_PATH / DYLD_LIBRARY_PATH system environment variable or copy the shared library to a system directory, as specified in the C/C++ Runtime Library Specification.

build/platform

The platform-specific subdirectory is used for building the corresponding demo executables.

C_Demo.mk

The makefile is used to build the C_Demo executable for the respective platform.

C_Demosl.mk

The makefile is used to build the C_Demosl static-link executable for the respective platform.

cdemoextapi.mak

The makefile is used to build the cdemoextapi executable for the respective platform.

cdemosecure.mak

The makefile is used to build the cdemosecure executable for the respective platform.

cdemostate.mak

The makefile is used to build the cdemostate executable for the respective platform.

src

The directory contains source code for demo applications.

C_Demo.c

This is the source code to the simple C_Demo C demo program described above.

cdemoextapi.c

This is the source code to the cdemoextapi extended API C demo program described above.

cdemosecure.cpp

This is the source code to the cdemosecure antispoofing C++ demo program described above.

cdemostate.c

This is the source code to the cdemostate secure state management C demo program described above.

include

This directory contains C/C++ header files for inclusion by your C/C++ application source code. For the most part, the only header file that is actually included in a C/C++ application program is ezLicenseInfo.h, which automatically includes the remaining header files other than Signature.h and PkCrypt.h. However, application developers will want to view the contents of these header files while writing code. If your application performs signature checks, the source code will also include Signature.h and PkCrypt.h.

ezLicCustomKeyHandler.h

This file defines the signature for the custom key handler that can optionally be specified when checking a license key, for the purpose of processing custom keys embedded in the generated keys.

ezLicLimits.h

This file defines upper limits on key sizes and other license management parameters for use in C and C++ programs.

ezLicenseExtAPI.h

This is the header file that defines the extended API calls for activating, checking and deactivating a license

ezLicenseInfo.h

This is the header file that defines the core API calls for checking license keys as well as for retrieving the various key parameter values following a successful key check.

ezLicStatusCodes.h

This file defines the error and warning status codes returned by the EasyLicenser API calls.

IlsPlat.h

This is an internal header file for platform independence. It is implicitly included by ezLicenseInfo.h, and does not need to be viewed by the developer.

PkCrypt.h

The file defines API's for public key cryptography API calls used in conjunction with signature checks.

Signature.h

The file defines API's for performing signature checks.

lib/platform

The platform-specific directorys contain the respective run time library binary files.  Your C/C++ application developer will deploy these binary files together with your corresponding license protected applications, when your applications are dynamically linked to them.

Include it in your PATH / LD_LIBRARY_PATH / DYLD_LIBRARY_PATH system environment variable as specified in the C/C++ Runtime Library Specifications, and also add the corresponding instructions in your C/C++ product installation guide for your customers to include in their PATH / LD_LIBRARY_PATH / DYLD_LIBRARY_PATH system environment variable the directory in which your installer deposits these library files at the time your customer installs your product at their site.

ezLicenserlib20.so, ezLicenserlib20.dll

This is the EasyLicenser C/C++ run time library binary. Note that as of EasyLicenser 2.0, the C/C++ runtime library shared library is no longer versioned, and is frozen at "20". So for EasyLicenser 2.5, the applicable C/C++ DLL / shared library is ezLicenserlib20.dll / ezLicenserlib20.so, not ezLicenserlib25.dll / ezLicenserlib25.so.

ezLicenserlib20.a, ezLicenserlib20s.lib

These are the static library versions of the above shared libraries and are intended to be statically linked with your application.

ezLicenserlib20-sig.txt

The text file contains the signature for the corresponding library. The signature is generated by Agilis and can be used as-is. Alternatively, you can use the makelibdigest utility described below in order to generate your own signature.

In addition, the Windows directories contain a matching ezLicenserlib20.lib import library for a Visual C++ application to link into the application in order to be able to use the DLL.

util/bin/platform

The platform-specific subdirectory contains respective utility binary files, which are used by you at your site as part of your development activities, and by your end customer for performing licensing related administration activities.

makelibdigest, makelibdigest.exe

The utility is used to generate signatures for the run time libraries for the respective platform. It can also be used by your end customer to check a signature provided by you. Use of the utility is optional: you can directly use the signature files distributed by Agilis together with the libraries.

ezlmgetmachineinfo, ezlmgetmachineinfo.exe

The utility is used by your end customer to generate machine node locking information that you collect and input into the key generation process when you issue a key to your end customer as part of order fulfillment. The node locking information is equally applicable to keys generated for Java and C/C++ protected applications.

data

This is the directory that contains the License Manager database files.  Its contents are not intended for direct viewing or manipulation.

demo

This directory contains Java sample code that can be used by your Java application developer as a headstart for license protecting your Java applications.

jdemo.java

This is a simple Hello World program that checks a given list of license keys for validity against a given user / host name. If the key is valid, it is decomposed and its parameters are displayed. Otherwise, an error message is displayed.

The program illustrates how to use the Java API's to perform simple license key checks.

To see how to run the program, type run jdemo with no arguments. The program expects up to four arguments: the name of a text file that contains a license key to check, the user / host name that allegedly matches what is in the key, and optionally (if inputting keys generated for password-protected products) a product name and an application password's public key. The text file may be in any of the license key export or publish formats supported by EasyLicenser.

The program’s intent is to illustrate at a basic level how the Java license key runtime library API’s are used in a Java application program. The code that reads the file containing the key can also be used as a head start by an application developer for reading in key information.

jdemo.class

This is the class file that is the output from compiling jdemo.java.It is executed with the run command files described below.

jdemoextapi.java

The demo program illustrates use of the extended API's for deferred-mode licensing and automatic metering. The program is invoked multiple times, initially in activation mode, then in license checking mode, and finally in deactivation mode. The dojdemoextapi.bat and dojdemoextapi.sh command files encapsulate the multiple invocations for convenience and also illustrates parameter usage.

To see how to run the program, run jdemoextapi with no arguments. The program expects up to eight arguments: a command indicating activation / check / deactivation, the name of a text file that contains a license key to activate, a product name and corresponding application password's public key, the user / host name that allegedly matches what is in the key, an optional auxiliary key for enabling deferred-mode licensing, an optional "used-quota increment" value representing quota consumption, and optionally an explicit hidden file directory specification. The text file for the license key may be in any of the license key export or publish formats supported by EasyLicenser. The text file for the auxiliary key is in raw key format.

jdemoextapi.class

This is the class file that is the output from compiling jdemoextapi.java. It is executed with the run command files described below.

jdemosecure.java

The demo program illustrates how to use EasyLicenser's anti-spoofing security mechanisms. The program makes use of the secure license key check and key cookie API's, digital signature checking, exception based flow control, dynamic invocation and custom key handlers. The program checks a given license key for validity against a given user / host name and also manages and checks for the current metered consumption in persistent store.

To see how to run the program, type run jdemosecure with no arguments. The program expects up to five arguments: the name of a text file that contains a license key to check, the user / host name that allegedly matches what is in the key, the name of a text file containing the signature of the EasyLicenser run time library, and optionally (if inputting keys generated for password-protected products) a product name and an application password's public key. The text file may be in any of the license key export or publish formats supported by EasyLicenser.

jdemosecure.class

This is the class file that is the output from compiling jdemosecure.java. It is executed with the run command files described below.

jdemostate.java

The program illustrates secure state management using the secure license key check and key cookie API's. It checks a given license key for validity against a given user / host name and also manages and checks for the current metered consumption in persistent store. The program is invoked multiple times. The docjdemostate.bat and dojdemostate.sh command files encapsulate the multiple invocations for convenience and also illustrate parameter usage.

To see how to run the program, type run jdemostate with no arguments. The program expects up to five arguments: the name of a text file that contains a license key to check, the user / host name that allegedly matches what is in the key, a "used-quota increment" value representing quota consumption, and optionally (if inputting keys generated for password-protected products) a product name and an application password's public key. The text file may be in any of the license key export or publish formats supported by EasyLicenser.

jdemostate.class

This is the class file that is the output from compiling jdemostate.java. It is executed with the run command files described below.

compile.bat

This is a DOS command file for compiling the demo programs on Windows. It accepts as an argument the name of the Java demo source program without the .java extension.

compile.sh

This is a Unix Bourne-compatible shell command file for compiling the demo programs on any Unix or Linux platform. It accepts as an argument the name of the Java demo source program without the .java extension.

dojdemoextapi.bat, dojdemoextapi.sh

The command file that performs multiple invocations of jdemoextapi to illustrate the cycle of activation, license checking, and deactivation.

dojdemostate.bat, dojdemostate.sh

The command file that performs multiple invocations of jdemostate to illustrate state management.

run.bat

This is a DOS command file for executing the demo programs on Windows. Invoke the command with the name of the demo program to execute less the .class extension, together with the program's arguments. For help on how to invoke the command, invoke it with no parameters and study the usage message that is displayed.

run.sh

This is a Unix Bourne-compatible shell command file for executing the demo program on any Unix or Linux platform. Invoke the command with the name of the demo program to execute less the .class extension, together with the program's arguments. For help on how to invoke the command, invoke it with no parameters and study the usage message that is displayed.

errlog

The purpose of this directory is to collect problem reports on EasyLicenser without inconvenience to you. Whenever the License Manager encounters a bug, it appends an entry to an error log file named errlog.txt and also deposits a log file in this directory and provides you with the fully qualified name of the file in a dialog box as well as the opportunity to have the bug automatically transmitted to EasyLicenser technical support over the Internet without your intervention..  If you prefer, you can email the file(s) to EasyLicenser technical support at your convenience.  EasyLicenser development staff will utilize the information to fix bugs in the next release of the product or provide you with a patch.

export

This is the directory that is presented to you by default when you use EasyLicenser to perform imports and exports of customer, product and license key data.  You are not required to use this directory.

extlib

The contents of this directory are mostly pertinent to the internal functioning of the License Manager GUI, with the exception that the file ilscrypt10.jar is required to be redistributed with your application together with the ezlicrun25.jar run time library in the lib directory.

html

The contents of the directory exactly correspond to the information that is accessible through the License Manager help facility.  The directory is provided for your convenience only, should you choose to view the product documentation using a conventional browser.  Removing the directory has no impact on the proper functioning of the program.

lib

For the most part, the contents of the directory are pertinent only to the internal functioning of the License Manager.  The directory also contains the following libraries that are meaningful to your Java application developers and operations staff:

ezlicgen25.jar

Your eCommerce application developer imports this library into Java code for programmatically generating keys.

ezlicrun25.jar

Distribute this library with your product binaries.  Your products’ Java application developers import the library into the application code for checking your license keys at your customer sites where your products are deployed.

ezlicutil25.jar

Distribute this library to your end user together with the ezlicmgrmcinfo25.jar executable jar and the associated ezlmgetmcinfo.bat or ezlmgetmcinfo.sh command file for the purpose of obtaining node locking information from your customer.

ezlicgen25-sig.txt

This is the Agilis-generated signature file for ezlicgenVV.jar. Typically you wouldn't use this since you wouldn't be redistributing the jar. It is used internally by EasyLicenser.

ezlicrun25-sig.txt

This is the Agilis-generated signature file for ezlicgen25.jar. Typically, you would use this in your application in order to protect it from a spoofed run time library. Alternatively, you can generate your own signature based on a secret password known only to you with the included makelibdigest Java utility located at the util directory described below.

samples

The directory contains miscellaneous Java sample code and design notes for a variety of application scenarios.

util

The directory contains miscellaneous Java utilities for use in your development environment. These are over and above the command line tools that are provided as executable jar files in the product root directory. The directory contents include:

datetodays

This is a convenience utility program that is used to compute a value for the number of days from today, given a date. The value is then used to input to the license manager console for expiration days when generating time limited licenses (recall the license manager console expects an expiration value expressed in days from today). To run the utility, invoke it with a class path equal to the utility directory path.

makelibdigest

This is the utility program that is used to generate signatures. To run the utility, invoke it with a class path that includes the ilscrypt10.jar library located in the extlib directory.

sysinfo

This is a convenience utility program that is used to introspect the Java system environment. The value is useful for performing diagnostics. To run the utility, invoke it with a class path equal to the utility directory path.

Running The License Manager

The License Manager Graphical User Interface program is run using standard mechanisms for running Java programs that are packaged as executable Jar files.  It is not necessary to define or modify CLASSPATH, PATH or other environment variables.

All Platforms Including Windows

Open a command window and position to the product installation root directory.  For example:

C:> cd \myproducts\ezlic2.5

Invoke the product executable Jar file using the ezlicmgr batch or shell command file that is provided for you.  For example:

C:\myproducts\ezlic2.5> ezlicmgr.bat


(On Unix / Linux systems, the equivalent would be: ezlicmgr.sh)

-Or-

Directly invoke the Java virtual machine on the product executable jar file. On all platforms, this is java. On Windows, it may be javaw. For example, on Windows:

C:\myproducts\ezlic2.5> C:\Program Files\java\jre1.5.0_09\bin\javaw -jar ezlicmgr25.jar

Depending on whether your Java installation modified your PATH environment variable to include its binary directory, it may be necessary to qualify the executable with the full path to the binary.

Windows Only

You can also invoke the License Manager using standard Windows mechanisms:

From Windows Explorer

Navigate to the product root directory and double-click on the ezlicmgr25.jar executable jar file.

From The Task Bar

Select Start … Run, browse to the product root directory and select the ezlicmgr25.jar executable jar file.

You can also create a desktop shortcut to the executable jar file using standard Windows mechanisms if you prefer.

Important Note: on old Windows machines (those manufactured prior to the date of the accord between Microsoft and Sun, circa 2004), the above mechanisms will not work if Microsoft's Java virtual machine is selected by default. Even if you install Sun's Java software and it takes effect as the default Java virtual machine when you use Explorer or the Start menu, the default may be overridden when you subsequently install Microsoft software or patches. Therefore, be prepared to resort to the command line mechanism if you execute the jar using these mechanisms and nothing happens or illogical Java errors are reported.

First Time Execution

When you first run EasyLicenser after downloading and unzipping the product, EasyLicenser is in evaluation mode even if you intend to utilize a production key that is provided to you by Agilis.  If your download procedure did not ask you to accept the terms of the license agreement, you will be prompted to accept the license terms and optionally register your product.  If you don’t register your product at this time, you can always register later.  If you are an evaluator, it is to your advantage to register your product as it enables you to receive news and information on EasyLicenser.

In order to enable your evaluation copy for production, go to the My License menu, select the Manage My License menu item and click on the Recharge button towards the bottom left hand corner of the dialog box that is presented to you (see the License Manager User Guide for a graphic illustration). You will be prompted for your product license key, which was emailed to you by Agilis as part of subscription order fulfillment.  Select your license key file using the file chooser dialog box and click Recharge EasyLicenser Installation, and you should immediately see the updated license information on the dialog box.

It is important to enter your product license key promptly upon receiving the key from us, as it is designed to be perishable for security reasons.

Every Execution

Upon program startup, you will be asked to enter a unique and confidential user name that is agreed upon between you and Agilis.

Running The License Management Command Line Utilities

The command line utilities are packaged as executable jar files, accompanied by convenience command file wrappers whose use is optional.

As with any executable jar file, the program can always be invoked as follows (taking ezlicmgrgenkey25.jar as an example):

    java -jar ezlicmgrgenkey25.jar <<params>>

Alternatively, the corresponding shell command can be invoked instead:

    ezlmgenkey.sh <<params>>

To obtain help information on how to run any command line utility and what parameters it takes, invoke the utility without any parameters.

All utility programs require positioning the current working directory to under the product root directory.

Setup For Programmatic Key Generation

In order for your Java program to successfully generate keys using the ezlicgen25.jar library, it is necessary for the program to be executed with the current working directory set to the product root directory.  Do not attempt to copy or relocate the product directory tree, otherwise key generation will be unsuccessful.

If the installation root directory requirement is too restrictive, you can instead download the product upgrade zip file, which does not create the ezlic2.5 directory and instead deposits all files and directories starting at the currently-positioned directory without affecting existing configurations. The download URL for the upgrade zip file is provided to you by Agilis. After unzipping, run the License Manager GUI on this directory in order to enter your production key directly. Subsequently, use the GUI in order to recharge your production EasyLicenser key whenever you receive a renewal key from us. Alternatively, you can use the recharge EasyLicenser installation key generation API to programmatically perform the recharge.

Managing Your EasyLicenser Product License

Whenever you generate keys, either with the License Manager user interface or directly with the key generation API’s or the corresponding key generation command line utility, your license unit balance quota is depleted.  Ordinarily, this should not be a problem, as Agilis provides an adequate number of license units in accordance with the terms of your subscription license agreement with Agilis. Nevertheless, unless you have a perpetual license agreement with Agilis, you will need to update your time-limited EasyLicense license key at least at the end of every term, typically once a year.

In order to replenish your quota and / or extend your license for another term, you will receive an additional key from Agilis under the terms of your subscription license agreement. You can use the License Manager user interface to input the new key using the My License menu. Alternatively, you can use the recharge command line utility, or the recharge EasyLicenser installation API call that is part of the key generation library.

Backing Up And Restoring Your License Database State

The state of your license key database and configuration can be backed up periodically using the File menu’s Backup command of the License Manager user interface.  Should it be necessary to do so, the Restore command may be used to restore the state of the configuration and license key database.

When a Backup command is issued, all database files as well as the configuration file are backed up in one consistent unit to a specified target file having a .ezb extension. When EasyLicenser state is restored from a backup, the complete state is restored to the point in time at which the backup was made, and all update activities that occurred subsequent to the backup are lost. If the restore is performed to a machine / account / directory location that is different from the location at which the backup was performed, only the data is restored, and the state of the EasyLicenser license configuration is unaffected.

It is good practice to perform frequent backups, to minimize data loss in the event of a hard disk crash.  For this same reason, backups should be performed on a separate disk located at a different machine from the one on which EasyLicenser is installed.

Deactivating Your EasyLicenser Installation

At some point, you may want to perform another installation of EasyLicenser on the same host account and transfer data from the current installation, for example to upgrade to a new release or set of options. Before you activate your new installation, it is necessary to deactivate the current installation. This is accomplished with the File menu's Deactivate command. Deactivation clears out the state of the installation but does not erase the data, backup or export directory contents. Deactivation also prompts you to produce a final backup, which you can provide to EasyLicenser support if requested by us.

For an eCommerce installation where no License Manager GUI is present, you may use the new deactivate command line utility or the deactivate EasyLicenser installation API call to perform the deactivation. The API call returns a confirmation token which you can provide to Agilis if required.

The reason for the existence of the deactivation facility is to help you effortlessly manage your compliance with the terms of our product license agreement.

Uninstalling EasyLicenser

At some point, you may want to uninstall EasyLicenser altogether. To do this, you will first perform a deactivation per the above procedure, and then remove the ezlic2.5 directory and its contents.

Deploying The EasyLicenser Run Time Library With Your Applications

Java on all platforms

Deployment simply consists of making a copy of ezlicrun25.jar located at the lib subdirectory and including it with your product distribution.

C/C++ on all platforms

Deployment consists of making a copy of ezLicenserlib20.so (Solaris, Linux, Mac OS X) or ezLicenserlib20.dll (Windows) contained in the respective platform-specific subdirectory of cpp/lib, and including it with your product distribution.

The above discussion is pertinent only if your application uses dynamic linking. If your application is statically linked with the static library version of the EasyLicenser runtime library, there are no deployment issues as far as the EasyLicenser runtime library is concerned.

Impact Of Run Time Library On ISV Product Installation

Your product’s installation instructions or preferably the installation process itself may need to be modified somewhat in order to deploy the EasyLicenser run time libraries, as follows (note that this also applies to the demo applications included with the EasyLicenser product distributions - the demos are in essence protected applications):

Java

Ensure that the Java class path factors in the EasyLicenser run time library jar file ezlicrun25.jar, the encryption library jar file ilscrypt10.jar, and (if performing signature checks) the directory containing the run time library.

C/C++ on all platforms

The following discussion is pertinent only if your application uses dynamic linking. If your application is statically linked with the static library version of the EasyLicenser runtime library, there are no deployment issues as far as the EasyLicenser runtime library is concerned.

On Windows, your product installer should place ezLicenserlib20.dll in your product installation binary files directory, and programmatically update the PATH system environment variable to include the binary file directory independent of EasyLicenser. The next best choice is to select an operating system binary directory, for example C:\Windows and deposit the libraries there, noting the fact in your uninstall script for future uninstallation.

On all other supported Solaris, Mac OS X and Linux platforms, your product installer should place the file ezLicenserlib20.so, contained in the respective platform-specific subdirectory of cpp/lib, in your product installation binary files directory, and programmatically update the PATH, (on Solaris) LD_LIBRARY_PATH, or (on Mac OS X) DYLD_LIBRARY_PATH system environment variable to include the binary file directory independent of EasyLicenser.

The above discussion is intended to provide a general flavor of the deployment process. For complete and precise platform-specific information on deployment of the C/C++ runtime dynamic libraries, please refer to the corresponding section of C/C++ Runtime Library Specification.

Deploying The EasyLicenser Redistribution Tools To Your End Customers

The redistribution tools, packaged in the ezlmredist25.zip zip file, consist of tools you provide to your end customers for administration and diagnostic purposes. The content and composition of the toolkit will vary over time as new EasyLicenser releases are issued - these are described in the readme file included with the zip file. Currently, the toolkit includes a Java utility to retrieve OS-level node locking information for generating OS node-locked license keys for both Java and C/C++ protected applications, and a diagnostic utility for introspecting the Java runtime environment, as described above under Directory Tree - Files.

Next Steps

Read the EasyLicenser Concepts guide to obtain an understanding of what EasyLicenser does and how to harness it effectively.  For detailed instructions on how to use the License Manager graphical interface, see the License Manager User Guide.  The Java ISV Application Development Guide describes how to license-enable your Java application with EasyLicenser.  Guidelines for programmatically generating keys from an eCommerce web site are available in the Java eCommerce Application Development Guide. The C/C++ ISV Application Development Guide describes how to use the EasyLicenser C/C++ run time library API’s to license-enable your C/C++ application.


Copyright © 2002+ Agilis Software LLC, Santa Clara, CA, USA. All rights reserved.