README For EasyLicenser 2.5
===========================

Product Documentation
---------------------

This is a README file only.  The full product documentation can be 
accessed by unzipping the product distribution and either running 
the License Manager GUI or directly pointing any web browser to
the file "ezlmhelp.html" located at the "html"directory under "ezlic2.5".  
Please view the "Setup" guide before running the License Manager.

After the License Manager is activated, you should be able to
access the documentation from your default web browser or (if
the License Manager is unable to locate your browser) built-in
document browser by clicking on the "Help..Help Topics" menu command.


System Requirements
-------------------

  License Manager, Java API's, Java SDK:

    Operating System:
        Any Unix, Linux, Windows or Macintosh platform
        supporting Java 1.4.2 and above.
    Hardware:
        128M+ RAM
        600MHZ+ CPU
        20M+ Hard disk space
    Display:
        Minimum resolution: 1024x768
        Recommended resolution: 1280x800
    Software:
        Java runtime 1.4.2 and above.

  C/C++ EasyLicenser Run Time Library 

    Operating System:
    	Windows 32-bit: 9x, NT 4.0, 2000, XP, Vista
	Linux-Intel 32-bit: Base 2.4 kernel, GNU gcc 3.3+
        Solaris-Intel, Solaris-SPARC 32-bit: Solaris 10,
            GNU gcc 3.4+
    Windows Run Time Support:
    	Microsoft C/C++ Runtime

  System clock accurate to within 2 hrs.  The software
  will malfunction if the clock time is changed significantly 
  after installation.  Applications at end-customer sites may
  also fail if end users use keys you generate from a system
  having an inaccurate clock.

Types Of Installations
----------------------

  There are three types of installations that you can
  perform.  The type of installation depends on the
  download option that you selected when performing 
  a download at our web site.  These are:

  1. Full installation:

     Performs a complete and self-contained installation 
     of the License Manager GUI, the SDK for Java, C++ 
     and Visual Basic, and initializes the configuration
     to a 30-day time-limited evaluation. Existing data
     is erased.  The installation is deposited in a
     directory "ezlic2.5" which is created.

     The corresponding downloaded zip file is
     ezlicmgreval.zip

  2. Upgrade installation:

     Upgrades a full installation with the updated code,
     documentation and SDK for a new release.  The existing
     configuration and data are unaffected.  No "ezlic2.5"
     directory is created - you will need to unzip directly
     into the existing product installation root.

     The corresponding downloaded zip file is
     ezlicmgrupgrd.zip


  3. Installation for eCommerce environment:

     Installs just the components of EasyLicenser that are 
     needed to deploy EasyLicenser for programmatic key 
     generation and to optionally run the License Manager GUI 
     for the purpose of recharging license units.  The SDK and 
     product documentation are not installed.  No "ezlic2.5"
     directory is created - you will need to unzip directly
     into the designated working directory for programmatic
     key generation.

     When you run the License Manager GUI for the first time
     following the installation, you will be prompted to
     approve a repair of the installation.  This is normal -
     click on the OK button.

     The License Manager GUI is not strictly speaking required: 
     a "rechargeEzlmKey" API call is available in the 
     EzLicenseFullInfo class for doing this programmatically,
     and a "ezlicmgrrecharge" command line tool is available for
     performing the recharge from a command line shell or script.

     The corresponding downloaded zip file is
     ezlicmgrecom.zip.

Special Notes On Installation For eCommerce Key Generation
----------------------------------------------------------

  EasyLicenser is designed to be run while positioned at
  the product installation root directory, which means
  the "user.dir" Java system property should match the 
  product installation root directory.
	
  If you are going to use EasyLicenser to programmatically
  generate keys with EasyLicenser, it is unlikely this will
  be under "ezlic2.5".  Therefore, in this case, you'll need
  to set the working directory for your web / application
  server accordingly.  For example, if you use Tomcat,
  you can override the default user directory by specifying
  a "-Duser.dir=c:\mydir" flag to the JVM either directly
  in the startup script or (Windows only) indirectly as part 
  of the Tomcat Windows NT service installation.


How To Run The License Manager Console
--------------------------------------

  Run the executable Jar file ezlicmgr25.jar in one of the
  following ways:
  (a) Windows: either double-click its icon or specify the
      file name in Start...Run
  (b) All platforms: open command line window, go to installation
      root directory, type "ezlicmgr.sh" / "ezlicmgr.bat".
      The second approach reports the currently-active Java version.
      On Unix platforms and Windows platforms equipped with a Unix
      Korn shell, the program is not run if a compatible Java
      version is not found.  In the event of a problem such as multiple 
      installed Java versions with the wrong version in effect, you 
      have the opportunity to correct the problem by specifying an 
      explicit path to the Java virtual machine in the command file.

      On some Unix platforms, it may be necessary to change permissions
      on "ezlicmgr.sh" and "chkjava.sh" to enable execution, by typing the 
      "chmod" shell command, for example:
          chmod +x ezlicmgr.sh

      On such platforms, also go to the "demo" directory and enable
      the execution permission similarly for "compile.sh" and "run.sh"

Reporting bugs
--------------

  When a bug is encountered, the License Manager console
  gives you the opportunity to allow it to be automatically
  reported to us over the Internet.  In addition,
  all bug reports are deposited in text files
  in the "errlog" subdirectory.  A log file
  "errlog.txt" also maintains a cumulative log of all bug reports.
  Should you choose not to have the bug reported over the
  Internet or are unable to do so, please visit our web site
  and submit a problem report, and provide us the contents of
  the bug file.  Alternatively, please email the contents of
  the bug file to "techsupport@agilis-sw.com".  Should we
  request it, please email us the contents of the entire
  "errlog.txt".

Uninstallation
--------------

  Run the License Manager GUI, and select File..Deactivate.
  Then exit the program and remove the ezlic2.5 directory and
  its contents.  If required, produce a final backup at the time
  of deactivation, and provide Agilis with this final backup.

  When deactivating an eCommerce installation, use the new
  "Deactivate EasyLicenser Installation" API call and provide
  Agilis with the confirmation token that is returned, if required.

  A "ezlicmgrdeact" command line deactivation tool is also available.

Upgrading / migrating from previous versions of EasyLicenser
------------------------------------------------------------

  Please refer to the upgrade instructions in the
  "What's New In EasyLicenser 2.5" chapter of the product
  documentation.

Compatibility Considerations
----------------------------

  Please refer to the discussions on the permutations of 
  compatibility considerations between new and old versions of
  EasyLicenser and between EasyLicenser 2.5 and Orion,
  covered in the "What's New In EasyLicenser 2.5" chapter 
  of the product documentation.

New features / platforms in EasyLicenser 2.5
--------------------------------------------

  Please refer to the discussions on new EasyLicenser 2.5
  features that are covered in the "What's New In EasyLicenser 2.5" 
  chapter of the product documentation.

Bug fixes in Release 2.5.01:
----------------------------

1. License Manager UI:
   1. Updating the application password for a product definition
      sometimes set the application password to its public key and
      regenerated the public key based on this public key instead
      of basing it on the original application password.
   2. Instead of reporting user friendly error messages, system
      errors were often displayed.
   3. During activation and possibly upon occurrence of internal
      errors, the License Manager could potentially hang for long
      periods of time when Internet access was restricted by a
      firewall.
   4. If one or more keys were generated but not published, and
      one or more new keys were generated *and* published, the
      published keys included the previously-generated keys.
   5. Network licensing options available in Orion 2.0.04 release
      were missing in the list of automatically-added options
      when the "Add Network Licensing Options" button was clicked
      in the product details screen.
2. Java Runtime Library:
   1. Keys generated with the "license to machine" license type
      didn't always work with the runtime library.
   2. The runtime library did not work on machines having multibyte
      character sets, when the username, installation directory,
      machine name or user home directory included multibyte
      characters.
3. C/C++ Runtime Library:
   1. Keys generated with the "license to machine" license type
      didn't always work with the runtime library.

Bug fixes in Release 2.0.01:
----------------------------
1. After the EasyLicenser license expired, the License Manager
   GUI would not come up successfully to allow the license to
   be recharged.
2. If prohibited characters outside 7-bit US-ASCII such as umlauts
   were entered for any field, no warning was issued.  Instead, a 
   system error occurred when the record was subsequently 
   accessed, rendering the information unusable.  This was
   particularly evident with customer records.
3. Import / export did not work properly with product data
   that had options specified with colons in their names.
4. Several fields allowed blank entries that subsequently resulted
   in system errors.  All fields are now strictly validated.
5. System clock checks didn't always work when using the basic run 
   time library license checking API's.

Bug fixes in Release 2.0.02:
----------------------------
1. (Regression, License Manager GUI) Beginning with 
   Release 2.0.00, license units for expired license 
   keys could not be reclaimed.
2. (Regression, runtime library, compatibility, all languages
   and platforms) Beginning with Release 2.0.00, 
   license key checks failed for keys having empty user/host 
   name strings.
3. (International character sets, License Manager GUI) 
   It was still possible for international-character-set characters 
   to cause the License Manager GUI to malfunction, under the 
   following scenarios:
   (a) entering certain 16-bit characters into data entry fields
       was permitted and resulted in corrupt product / customer /
       license key data in the database.
   (b) it was possible to install EasyLicenser in a directory
       path containing characters other than 7-bit US ASCII.
       Subsequently, it was not possible to view or manipulate
       any information in the product / customer / license
       database.
4. (Access-controlled keys, C/C++ runtime library, Windows / Linux)
   If an application password was specified for a product and
   its length was less than 4 characters, access-controlled key
   checks failed at run time for C/C++ applications.
5. (License Manager GUI) Transitioning from evaluation to
   a production key via a recharge did not immediately enable 
   the time limit field - it was necessary to exit and restart the
   GUI in order to be able to generate a time limited key.

Upgrading to Release 2.5 from 2.0:
----------------------------------
1. Download http://www.agilis-sw.com/ezlm/anondownload/ezlicmgrupgrd.zip
   instead of using or downloading ezlicmgreval.zip.
2. Position to within the existing product installation root directory
   (that is, in the ezlic2.0 or ezlic1.1 subdirectory).
3. Unzip the downloaded zip into this directory.  Your existing data files
   are preserved and are compatible with the new release.
It is recommended that you don't perform the upgrade unless you have
an EasyLicenser subscription license with Agilis and can therefore receive
EasyLicenser 2.5 enabled license keys for recharging.


Performing an installation for eCommerce with Release 2.5:
----------------------------------------------------------
1. Download http://www.agilis-sw.com/ezlm/anondownload/ezlicmgrecom.zip.
2. Position to within the targeted eCommerce system current working directory.
   This may be on any local drive and directory, so long as it is the
   current directory as perceived by your eCommerce Java program.
3. Unzip the downloaded zip into this directory.  Your existing data files
   if any are preserved and are compatible with the new release, and no
   "ezlic2.5" directory is created.
4. Run the license manager GUI per instructions before attempting any
   programmatic key generation.  The GUI will eventually ask you for a key.
   Supply the eCommerce production key directly.  You will also be asked for
   a user name.  The name you supply should match the user name that you
   were provided along with the key.  If this is the first time you are 
   performing an installation for eCommerce in this directory, the GUI
   will ask you if you want to repair the directory.  This is normal -
   click the Yes button.
   Alternatively, use the new "recharge EasyLicenser installation" API call
   to programmatically add license units to your eCommerce installation,
   or the equivalent "ezlicmgrrecharge" command line tool -
   in this case, you don't need to use the License Manager GUI.
5. Whenever the license units on the eCommerce site need to be recharged,
   be sure to use the license manager GUI to perform the recharge, and
   perform this operation offline while the eCommerce system is not running.

Known problems / issues / bugs
------------------------------
1. The product's built-in help facility (used if EasyLicenser is
   unable to launch an external browser on the host machine
   for some reason) does not properly
   support predictable and consistent navigation within 
   a page.  It is often necessary to click on a link 
   more than once in order to arrive at the correct
   destination.  Workarounds:
   (a) Re-click once or twice and navigation to the correct
       destination will eventually occur.
   (b) It is preferable to use a traditional browser to view
       the documentation.
   The help system also does not always properly render the
   content at the level of a standard browser.
2. (Windows) The Edit.. Select All menu does not always work.  
   The workaround is to perform a Ctrl-A shortcut.
3. In the Key Details screen, it is possible to edit the
   key options, even though the changes aren't reflected
   in the (readonly) key.
4. When entering or editing values in a table cell or the
   label of a tree view, it is necessary to explicitly 
   change the focus to another cell in order for the data 
   entry to take effect.  If, after entering or editing 
   data in a table cell you hit an action button, your 
   changes have no effect.  This problem manifests itself
   in all tables and file chooser dialogs.
5. On Windows, the License Manager GUI might not work on 
   network-mounted directories if their timestamps are not
   managed correctly by their host machine - only a local C:, 
   D: etc. drive may be used.
6. When starting the License Manager from the command line,
   spurious "Error assimilating ..." messages are displayed on
   the console.  These may be safely ignored.
7. The C/C++ runtime library might not function on machines having
   multibyte character sets installed under certain circumstances.
8. The License Manager UI might not be able to automatically launch 
   an installed web browser in the event of a system misconfiguration -
   in the event this happens, you will be redirected to EasyLicenser's
   built-in document browser.

Important security notes
------------------------
1. Because your customers have equal access to EasyLicenser
   software, the audit feature can allow them to analyze
   your keys if they know your username.
   For this reason alone, do not distribute any information
   on your user name to your customers with the keys.  If you
   wish to distribute exported keys in XML, CSV or TAB files
   and the exports were produced by versions prior to 1.1.01,
   you should scramble the key unique identifier fields.  This
   is automatically done for you by EasyLicenser versions 1.1
   and later.  Note that the key identifier is not required 
   by your customers.
2. In order to prevent your customers from using a valid
   EasyLicenser license obtained from us in order to duplicate 
   keys you provide them (even if they constitute hard-enforcement), 
   you should define an application password for your product, and
   provide the corresponding public key (available in the product
   details screen) to the license key check API call at run time.
   Keep this password secret from your customers.
   Note that this new feature is not backward compatible with 
   previous versions of the runtime library.  Therefore, in 
   order to avail of this feature, you will need to update 
   your application logic and the embedded EasyLicenser 
   runtime libraries.
3. Ensure that your application uses the runtime license checking
   API call signatures that accept a "strict password check" parameter
   and pass a true value for this parameter.

Notes to EasyLicenser 2.5.00 Beta users
--------------------------------------
1. Command line tool naming conventions have been streamlined.
2. Two additional command line tools have been added:
   "ezlicmgrclonekey" for cloning / chaining keys, and
   "ezlicmgrkeyinfo" for displaying audit information on a key.
3. A "ezlmredist25.zip" tool redistribution package is defined for
   the purpose of redistributing utilities to end customers so that
   they are not required to install the full EasyLicenser product
   distribution.  Currently, the tools included with the package are 
   the "ezlicmgrmcinfo" machine information introspection utility and 
   the "sysinfo" Java system information introspection utility.

                         -x-

Last Updated 08/31/07 For EasyLicenser 2.5.01
