README For EasyLicenser 2.5.11 
==============================

Key theme of Release 2.5.11
---------------------------

The primary objective behind Release 2.5.11 is to provide usability and
security enhancements, and expand platform support for the C/C++ runtime
library.  The release also incorporates a number of bug
fixes.


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.

Information on the available Java and C/C++ demos is available in the 
Setup guide under the description of the product installation directory tree.


System Requirements For License Manager UI
------------------------------------------

   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.

  Complete system requirements, including Java runtime requirements
  for the Java runtime library and platform / compiler / IDE
  requirements for the C/C++ runtime libraries, are covered in the
  html documentaiton.

  The system clock is required to be 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 and the SDKs for Java and C++,
     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.

  You can use any zip-compatible utility including PKZIP, WinZip,
  unzip and jar.  Caution: on Solaris, if you use the "unzip"
  utility, directories have their execute permission removed, 
  so it is recommended that you use some other means of unzipping
  on this platform, for example "jar".

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.

  You may also contact Agilis about a separately-packaged
  EasyLicenser Http Server system that enables remote 
  http based key generation from an ecommerce system or
  a web browser.


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 
  "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.11" 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.11 and Orion,
  covered in the "What's New In EasyLicenser 2.5.11" chapter 
  of the product documentation.

New features in EasyLicenser 2.5.11
-----------------------------------

   These are described in the "What's New In EasyLicenser 2.5.11"
   chapter of the product documentation.

Bug fixes in Release 2.5.11:
----------------------------

1. License Manager UI:
   1. Key details didn't show product options if the product 
      definition was not available.
   2. Under certain usage patterns, viewing details of an invalid 
      key resulted in a system error due to a null pointer exception.
   3. When viewing key details and cloning keys from the license
      key work area or the Manage License Keys window, unexpected
      windows came under focus under error conditions.

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.

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.
4. Preferably, update your application to use the 2.5.11 runtime
   libraries, and generate and distribute (backward incompatible) "secure keys"
   to your customers.  Details on upgrading and compatibility 
   considerations are provided in the "What's new in EasyLicenser 2.5.11"
   chapter of the product documentation.

                         -x-

Last Updated 12/01/08 For EasyLicenser 2.5.11 Production Release

