Overview Of Setup, Management And Deployment
Activities
All Platforms Including Windows
Setup For Programmatic Key Generation
(eCommerce Option Only)
Managing Your EasyLicenser Product
License
Backing Up And Restoring Your License
Database State
Deactivating Your EasyLicenser Installation
Deploying The EasyLicenser Run Time
Library With Your Applications
C/C++ on all platforms and Visual Basic
6 on Windows
Impact Of Run Time Library On ISV Product
Installation
C/C++ on all platforms and Visual Basic
6 on Windows
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.
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.
Installation is a two-step process:
1. Download the product zip file.
At any time, 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.
2. Unzip the file.
Select an installation directory and unzip the file using any of the standard Zip-compatible utilities, such as Winzip on Windows or the “jar” utility included with the JDK on any platform. For example, on Unix:
$ cd ~/myproductsrootdir
$ jar xvf $DOWNLOADDIR/ezlicmgreval.zip
A “ezlicV.V” (V.V is the major version number, for example 1.1) 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.txt located at the product home directory.
You may install and activate at most one copy of EasyLicenser on a given host account. 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.
The product root directory is the “ezlicV.V” 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:
ezlicmgrVV.jar
This is the executable jar file that is invoked as described below under Running The License Manager. VV is the major version number, for example 11.
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 delete, replace or relocate this file, otherwise EasyLicenser will cease to function.
readme.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.
run
This is a Unix command file for running the License Manager Graphical User Interface program.
run.bat
This is a Windows command file for running the License Manager Graphical User Interface program from a command window.
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
This is the directory that contains the C/C++ run time library header files, libraries and sample application code. It is used by your C/C++ application developer.
The directory contains source and binary code for demo applications.
bin
The directory contains binary code for the demo applications.
win32
The directory contains MS Visual C++-built Windows binary demo code (“.exe” file(s)):
C_Demo.exe
This is the executable code for a simple “Hello World” C demo program that checks a given license key 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 license key checks ranging from simple checks to sophisticated, secure checks.
To see how to run the program, type C_Demo.exe with no arguments. The program expects two arguments: the name of a text file that contains a license key to check, and the user / host name that allegedly matches what is in the key. The text file may be in any of the license key export or publish formats supported by EasyLicenser.
In order to be able to run the program, it is necessary to meet the prerequisite of including the "cpp\lib\win32" directory in your PATH system environment variable, as described below.
hp_ux, linux, sun
The directory contains the binary executable file for the respective platforms: HPUX-HPPA, Linux-Intel and Sun Solaris-SPARC
C_Demo
This is the executable code for a simple “Hello World” C demo program described above. It is run as described above.
In order to be able to run the program, it is necessary to meet the prerequisite of including the "cpp/lib/<<platform>> directory in your PATH or LD_LIBRARY_PATH system environment variable, as described below.
build
The directory is used for building the demo executables.
hp_ux, linux, sun, win32
C_Demo.mk
This is the makefile for building the C_Demo executable for the respective platform.
src
The directory contains source code for demo applications.
C_Demo.c
This is a simple “Hello World” C demo program that obtains from the command line the name of a text file that is expected to contain a license key and the corresponding user / host name, and validates the key against the user / host name using a variety of EasyLicenser C run time API's ranging from simple to sophisticated and secure. After successfully checking the key, its parameters are displayed.
The program’s intent is to
illustrate how the C/C++ license key runtime library API’s
are used in a C or C++ application program for simple as well as secure license
protection. Sample code is also included that shows how to read a license
key from an exported / published data file.
include
This directory contains C/C++
header files for inclusion by ISV’s application programs. The only header file that is actually
included in a C/C++ application program is ezLicenseInfo.h, which automatically
includes the remaining header files.
However, application developers will want to view the contents of these
header files while writing code.
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.
ezLicenseInfo.h
This is the header file that defines the API calls for checking license keys as well as for retrieving the various key parameter values following a successful key check.
ezlmplat.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.
lib
This directory contains
platform specific run time library binary files within the appropriate
subdirectory. Your C/C++ or Visual
Basic 6 application developer will deploy these binary files together with your
corresponding license protected applications.
hp_ux, linux, sun, win32
This directory contains the platform-specific run time library binary file for the respective platforms: HPUX-HPPA, Linux-Intel, Sun Solaris-SPARC and Windows. Include it in your “PATH” or (for Solaris) "LD_LIBRARY_PATH" system environment variable, and also add instructions in your C/C++ product installation guide for your customers to include in their “PATH” or "LD_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.
ezLicenserlibVV.so, ezLicenserlibVV.sl, ezLicenserlibVV.dll
This is the EasyLicenser C/C++
run time library binary, where “VV” represents the major and minor version
number, for example “11” for version 1.1. The ".sl" suffix is
specific to HPUX, and the ".dll" suffix is specific to Windows.
In addition, the Windows directory contains a matching "ezLicenserlibVV.lib" import library for a Visual C++ application to link into the application in order to be able to use the DLL.
data
This is the directory that contains the License Manager database files. Its contents are not intended for direct viewing or manipulation.
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 accepts two command line arguments representing a text file name containing a license key to check, and a user or host name that is supposed to match what is in the license key. After successfully checking the key, its parameters are displayed. The input key file can be in any of the key export / publish formats generated by the license manager GUI.
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.
jdemosecure.java
This is a more complex variant of jdemo.java. The program performs multiple license key checks using a variety of API's and features.
The program’s intent is to illustrate how the Java license key runtime library secure API’s are used to build a spoof-proof Java application program.
jdemosecure.class
This is the class file that is the output from compiling jdemo.java. It is executed with the run command files described below.
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.
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.
run.bat
This is a DOS command file for executing the demo programs on Windows. Invoke the command with three parameters: the name of the demo program to execute less the ".class" extension, the name of a text file containing a license key to be checked, and the user or host name that is supposed to correspond to the key. 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 three parameters: the name of the demo program to execute less the ".class" extension, the name of a text file containing a license key to be checked, and the user or host name that is supposed to correspond to the key. 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 pertinent only to the internal functioning of the License Manager GUI.
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:
ezlicgenVV.jar
Your eCommerce application developer imports this library into Java code for programmatically generating keys, if your EasyLicenser comes with the eCommerce option.
ezlicrunVV.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.
samples
The directory contains miscellaneous Java sample code and design notes for a variety of application scenarios.
This directory contains Visual Basic 6 files and sample code. Your Visual Basic 6 application developer will refer to this directory when developing and deploying your license protected Visual Basic 6 applications. The Windows C/C++ run time library DLL located at the cpp directory will also be required in order for the Visual Basic 6 application to run.
This directory contains source and binary code for a demo Visual Basic 6 program that illustrates protection of a VB 6 program with the C/C++ EasyLicenser run time library.
bin
This directory contains the binary executable code for the demo program.
vb_demo.exe
This file is the Visual Basic 6 executable for the demo program described below. You can execute the program using any of the standard Windows mechanisms. However, you will need to ensure that your PATH system environment variable includes the directory containing the Windows EasyLicenser C/C++ run time library. Also, as with any Visual Basic 6 program, you will also need to ensure that the Visual Basic run time is installed on your machine.
build
This directory contains the command file for building the VB6 demo program.
build_vb_demo.bat
This file is the DOS command file used to build the demo executable.
src
This directory contains source code for the demo program in three files: VB_demo.frm, VB_Demo.vbp and VB_Demo.vbw.
The demo program presents a window that accepts a license key and a corresponding user name, and checks the key and displays its parameters upon being instructed to do so. Its functionality is similar to that provided by the License Manager GUI’s license key auditing facilities.
The purpose of the program is to illustrate how to use the EasyLicenser C/C++ run time library to license protect a Visual Basic 6 program.
src
This directory contains source code that is required to be used with VB6 programs for interfacing with the C/C++ run time DLL. The DLL interface file is ezLicenserlibVV.bas, where VV is the major EasyLicenser run time library version, for example "11" for Version 1.1.
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.
Open a command window and position to the product installation root directory. For example:
D:> cd \myproducts\ezlic1.0
Invoke the product executable Jar file using the “run” command file that is provided for you. For example:
D:\myproducts\ezlic1.0> run
-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:
D:\myproducts\ezlic1.0> c:\jdk1.3.1\bin\javaw –jar ezlicmgr11.jar
You can also invoke the License Manager using standard Windows mechanisms:
Navigate to the product root directory and double-click on the ezlicmgrVV.jar executable jar file.
Select Start … Run, browse to the product root directory and select the ezlicmgrVV.jar executable jar file.
You can also create a desktop shortcut to the executable jar file using standard Windows mechanisms if you prefer.
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 you have purchased. 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. Since there is an incentive to register your product in the form of a percentage increase in your license quota, it is to your advantage to register your product at this time.
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 at the time you made your credit card purchase. Paste the key into the text area of the dialog box and click “OK”, 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.
Upon program startup, you will be asked to enter a unique and confidential user name that was assigned to you when you first purchased a product license key. Please contact EasyLicenser sales if you have lost your user name information.
In order for your Java program to successfully generate keys using the ezlicgenVV.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.
Whenever you generate keys, either with the License Manager user interface or directly with the key generation API’s, your license unit balance quota is depleted. In order to replenish your quota, you may purchase an additional key for the appropriate quota at the easylicenser.com web site and use the License Manager user interface to input the new key using the My License menu.
Periodically, you can reclaim license units for time-limited keys that you have generated and which have expired. To do this, you use the My License menu in the License Manager user interface.
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.
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.
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. Therefore, prior to deactivation, you should export the data you wish to save.
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.
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 ezlicV.V directory and its contents.
Deployment simply consists of making a copy of ezlicrunVV.jar located at the lib subdirectory and including it with your product distribution.
Deployment consists of making a copy of "ezLicenserlibVV.so" (Solaris, Linux), "ezLicenserlibVV.sl" (HPUX) or "ezLicenserlibVV.dll" (Windows) contained in the respective platform-specific subdirectory of "cpp/lib", and including it with your product distribution.
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:
Ensure that the Java class path factors in the EasyLicenser run time library jar file ezlicrunVV.jar. For example, if you provide a command file for executing your Java program, the class path specification provided inline in the command line should also include ezlicrunVV.jar.
On Windows, your product installer should place “ezLicenserlibVV.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 and deposit the libraries there, noting the fact in your uninstall script for future de-installation.
On all other platforms, your product installer should place the file "ezLicenserlibVV.so" (Solaris, Linux) or "ezLicenserlibVV.sl" (HPUX), contained in the respective platform-specific subdirectory of "cpp/lib", in your product installation binary files directory, and programmatically update the PATH or (on Solaris) LD_LIBRARY_PATH system environment variable to include the binary file directory independent of EasyLicenser.
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. The Visual Basic 6 Application Development Guide describes how to use the EasyLicenser C/C++ run time library API’s and the corresponding DLL interface module for Visual Basic 6 to license-enable your Visual Basic 6 application.