License Manager User Guide
Selecting License Model And Type
Exporting Customer / Product / Key Data
Importing Customer / Product / Key Data
Managing The EasyLicenser Product License
Backing Up EasyLicenser Configuration
Restoring EasyLicenser Configuration
When you log on to EasyLicenser, you are presented with the main screen, which is organized to support the primary activity: generating keys. From the menus, you can also perform auxiliary tasks such as backups and the management of customers, products and keys.
The following diagram illustrates the layout of the main License Manager Professional Edition screen:
From the menu, you can initiate auxiliary activities:
File Management
The primary file management activity is that of backing up and restoring your EasyLicenser configuration. In addition, you can use the Deactivate menu command in order to deactivate your EasyLicenser installation so that you can upgrade or migrate to a new installation on the same machine.
Edit
Standard edit functions are available for operating on text areas and fields. The operations apply only to the text area or field that is currently in focus.
Product Management
Product management functions are used to create and manipulate the definitions of your products for which you wish to generate license keys.
Customer Management
Customer management functions are used to create and manipulate the definitions of your end customers for whom you wish to generate license keys.
License Key Management
License key management functions are used to manage keys that you have already generated. Managing a key encompasses activities ranging from searching for keys and related customers according to a number of critieria, to auditing specific keys.
EasyLicenser License Management
Managing the EasyLicenser license consists of viewing the details of your license to use EasyLicenser, adding to your license quota, and reclaiming quota for keys you generated that have expired.
Obtaining Help
The help menu launches a built-in browser, which is pre-loaded with the table-of-contents information. From the table of contents, you can navigate to all product documentation, including reference documentation on the programming API’s.
You can also directly launch a traditional browser such as Internet Explorer or Netscape to view the help information. In this case, the starting point is $ROOTDIR/html/ezlmhelp.html, where ROOTDIR is your EasyLicenser installation root directory.
In addition, context-specific help information is available with each menu item and command button, and is accessible by moving the mouse cursor over the user interface element:
You can reach the customer definition screen in one of two ways:
(a) When you directly type in a customer name in the customer / product selection area instead of using the Choose button to select from available customer definitions and the customer name does not exist, you are prompted to confirm whether you want to create the nonexistent customer:
(b) When you select the Add command in the Customers menu.
The customer data entry dialog consists of three sections organized as a tabbed pane. The dialog is shown below with the default main tab selection.
The custom fields are optional and may be used to enter any information associated with the customer.
The dialog does not automatically close upon creating a customer record. Instead, all the fields are cleared so as to ready the dialog for data entry of the next customer.
Select the Customer Contact tab to enter the contact information of the customer representative of the company:
The custom fields are optional and may be used to enter any information associated with the customer representative.
Select the ISV Contact tab to enter information on your sales representative who is assigned to the customer account:
The Notes field may be used by your sales representative to record notes on conversations and interactions with the customer.
You can reach the product definition screen in one of two ways:
(c) When you directly type in a product name in the customer / product selection area instead of using the Choose button to select from available product definitions and the product name does not exist, you are prompted to confirm whether you want to create the nonexistent product:
(d) When you select the Add command in the Products menu.
The product data entry dialog consists of two sections, one for defining a product name and another for defining the available options for the product:
The dialog does not automatically close upon creating a product record. Instead, all the fields are cleared so as to ready the dialog for data entry of the next product.
When defining an option, either a default value or a semicolon-separated list of possible values may be specified. If a default value is specified, this the value that is displayed for the option at key composition time, and may be overridden with an arbitrary value not containing the ':' character. If a list of values is specified, the first value is displayed at the time of key composition, and may be overridden with any value in the list.
The process of composing and generating a batch of keys consists of performing the following steps in that order:
- Choosing the product and customer for which the keys will be generated.
- Selecting the license model and type, and providing the appropriate parameters for user or host name.
- Specifying the license parameters and determining whether to enforce an operating system check.
- Specifying the key generation criteria.
- Generating the keys into the license key work area.
- Managing the generated keys in the license key work area.
Allowed Character Set
Unless noted otherwise, the text fields values that you specify during key composition may not contain the ':' character. Individual fields may have additional restrictions which are noted in their respective documentation.
Choosing Customer / Product
You can either click the Choose button and select an item from the list of available customers / products, or as a short cut type it in directly. If you type the name and it doesn’t exist, you are prompted with the option to define the customer or product whose name you entered, as described above.
Selecting License Model And Type
The Standard Edition supports the User license model. With the Professional Edition, you can select between User and Server license models:
Associated with the User license model, you can choose between Named User and Host licensing:
You are accordingly prompted for a unique user or host name:
If you are using the Professional Edition and you select the Server license model, you can choose between Named User, Concurrent User, CPU Count and CPU MHZ license types:
You are prompted for a unique server host name and the associated user / CPU parameter according to your selection:
If you are enforcing built-in operating system checks (see below), the user name must correspond to that provided by your end-customer for the machine on which they will be running your secured application. Your end-customer provides this information by looking up their user name through a "whoami" or equivalent operating system command on Unix / Linux systems, and by pressing CTRL-ALT-DEL on Windows systems.
Similarly, the host name corresponds to your end-customer's machine name. On Unix / Linux systems, you r end-customer can obtain this information by typing the "hostname" or equivalent command. On Windows, pressing CTRL-ALT-DEL as above will provide the machine name information.
With user licensing and operating-system enforcement, you also have the option of enforcing both a user name and a machine name, by specifying the user name with the following syntax:
user@machine
For example: root@linuxmachine
Specifying License Parameters
There are three types of license parameters (two for the Standard Edition), organized into a tabbed pane. With the Pro edition, these are accompanied by a checkbox to enable built-in operating system enforcement of the user / host name specification.
The license parameter tab panes and the operating-system-check selection checkbox are illustrated below.
In order to utilize the built-in operating system check mechanisms in the EasyLicenser run time library to match the user name and / or host name used to generate the key, select the "Enforce Operating System Check" checkbox (Pro Edition only). The syntax and semantics of the user and host name specification are described above.
The main tab pane is used to specify the most frequently-specified parameters for generation of metered and time limited keys.
The Advanced tab is used less frequently. It is used to override the default options that are associated with the selected product. Overriding the product’s default options consists of selecting or deselecting an option, and overriding the default value with a value in the list of allowed values. The Advanced tab is illustrated below:
Depending on how you defined your product options, you can either accept the default value, override it with a value that matches an entry in the list of allowed values for the option, or override it with arbitrary text if a list of allowed value was not specified. The option value may not contain the special characters ':' and ';'.
With the Professional Edition, you can customize and extend your license key by specifying custom keys and cookies in the advanced tab. The specific values that you use for these fields are determined by you, and the only constraint is that the values cannot contain the ‘:’ character. If you wish to specify a list of name-value pairs for a custom key or cookie value, you can use the ';' separator character in order to enable you to use the EasyLicenser run time library utility to automatically produce a hash map from the list.
The Custom tab is illustrated below:
Specifying Key Generation Criteria
In this section, you can specify whether multiple keys will be generated automatically, and whether the batch of generated keys will automatically be published:
If the "Auto-Generate Multiple Keys" is selected, EasyLicenser makes up names for the user and / or host. This feature is useful if you need to produce a large number of keys that are not tied to specific customers. Conversely, if the keys you are generating are designed to be locked to specific machines or users, you probably want to deselect the option and enter each user / host name individually.
Generating Keys
When you click the Generate button, key generation proceeds automatically, and the generated keys are deposited in the license key work area. If the Auto-Generate checkbox was not selected, you are prompted for the user or host name for each key, as shown below:
In addition to being deposited in the license key work area, a generated key is also stored in an internally-maintained license key database.
After all keys are generated, if the Auto-Publish checkbox was selected, you are prompted to publish the selected generated keys:
The supported file formats for published keys corresponds to those for exported keys, described below under Exporting Customer / Product / Key Data.
Managing Generated Keys
After you have accumulated newly-generated keys in the license key work area, you can manipulate them individually or as a group as follows:
Customer records can be located according to search criteria and then manipulated, through the Manage Customers dialog:
The dialog for viewing customer details is very similar to the Add Customer dialog, with the difference that additional attributes are displayed, and you are provided with a button to update the record:
Product records can be located according to search criteria and then manipulated, through the Manage Products dialog:
The dialog for viewing product details is very similar to the Add Product dialog, with the difference that additional attributes are displayed, and you are provided with a button to update the record:
The license keys you have previously generated can be located according to a number of search criteria, and subsequently operated on, using the Manage License Keys dialog:
When the Details button is clicked for a single selected key, you can view (but not modify) the details of the key:
You can also directly enter this dialog from the menu to analyze the details of a specific key obtained directly from your customer, even if the key is not in your database.
You can view the details of a key only if you are its creator.
All data that is maintained in the internal database can be exported for the purpose of archival or external processing.
You can export data any number of times in any one of several formats according to the purpose of the export:
(a) Comma-separated values (.csv extension)
Each row of data corresponds to one line of text in the export file, with the individual fields separated by a comma. This format is suited for importing into databases and contact managers and for direct linking to database managers as external tables. It can also be used to archive the data so that it can be re-imported into EasyLicenser.
(b) Tab-separated values (.tab extension)
Each row of data corresponds to one line of text in the export file, with the individual fields separated by a tab character. This format is suited for importing into databases and contact managers and for direct linking to database managers as external tables. It can also be used to archive the data so that it can be re-imported into EasyLicenser.
(c) XML format (.xml extension)
The exported data is represented in XML format to permit automated processing using XML parsers and XSLT scripts. It can also be used to archive the data so that it can be re-imported into EasyLicenser. Data in this format is more verbose and occupies significantly more disk space.
(d) Formatted-text (.txt extension)
The exported data is formatted for human readability. It is suitable for making generated keys available to customers who will manually extract the keys for inputting into dialogs or property files. Exported data in this format cannot be imported into EasyLicenser.
In addition to the above export formats, license key data can be exported in two additional formats that are also applicable to key publishing:
(e) Property-file (.ini extension)
The exported data is formatted for direct use by a Java application. The file contains one line of text per key, consisting of a property-file format "licenseKey=<<key>>". It is suitable for producing single keys for Java (or other) programs that use property files containing name-value pairs. Exported data in this format cannot be imported into EasyLicenser.
(f) Raw-key (.key extension)
The exported data is formatted for direct use by an application, and consists of a line of text per key. The text is just the key value, without accompanying information. It is best suited for producing single keys that are directly inputted by end customers to the ISV applications. Exported data in this format cannot be imported into EasyLicenser..
The screen for performing an export is identical for any kind of data. The screen for exporting license keys is shown below:
Exporting license key data is different from publishing it; the latter activity is targeted at your end customer, and published data contains a restricted subset of exported data. Also, unlike an exported-keys file, a published-keys file cannot be imported into EasyLicenser.
It is important to note that when you export license key data, most of the formats will display additional information that represent the parameters of the key. The license protected application will only use the key itself, and this key is immutable. That is, the integrity of the licensing mechanism is not compromised if the contents of an exported- or published-key file are edited, for example in an attempt to increase a concurrent-user limit.
If you select an existing file for export, the export process overwrites its contents. Therefore, as a matter of practice, you should export to new file names.
You can import a previously-exported data file provided it is in a comma-separated, tab-separated or XML format. You can also import a comma-separated or tab-separated-value file having the expected fields which is the result of an export from a contact manager or a database management system.
The default export directory is used as the default repository for all six types of exported and published files. If you import a file of the wrong type (for example, if you import a published-keys file into the customer database), you will encounter file-format errors. It is therefore recommended that you define a naming convention that clearly differentiates the four kinds of files when these are presented to the user in the import dialog. For example, published keys can start with "keypub", exported keys can start with "key", exported customers can begin with "cust", and "prod" can be used as the prefix for exported products.
Importing a file is a little more complicated than performing an export: you have to decide what to do with bad and duplicate records. The import dialog offers you choices on what to do with such data – whether to abort the import process (in which case no records are imported), discard bad or duplicate records, ignore duplicate records or forcibly apply records having duplicate key values.
The screen for performing an import is shown below. It is identical for any kind of data.
The Manage My License modeless dialog box shows the details of your EasyLicenser license. It is updated as you generate keys, reclaim expired keys and recharge your license. The dialog is illustrated below:
The backup and restore mechanism is used to protect your EasyLicenser installation from catastrophic disk failures and file corruption. The backup operation is quick, and should be performed frequently in order to minimize the amount of lost information in the event of a disk failure.
Backing up the EasyLicenser state results in saving the state of the EasyLicenser configuration as well as the databases in a single backup file which can subsequently be used to restore the state of the configuration and / or database.
The standard File Chooser dialog for performing backups is illustrated below:
The backup file has a .ezb extension.
By default, backups are performed on a “backup” subdirectory of the EasyLicenser installation root directory. However, to protect from disk failures, you should select a different directory on a different disk.
The EasyLicenser configuration and database state can be restored from a previous backup through a standard File Chooser dialog, illustrated below:
You should restore your EasyLicenser state only in the event of a disk failure. If you perform a restore under normal circumstances, you can lose data because existing data is overwritten.
You can restore your backup to any existing EasyLicenser installation irrespective of the installation that you backed up. However, if the target installation is different from the original, it is required to have a valid license in order to operate; the original license is not transferred.
If your original installation is corrupted, however, you can perform a full restore to it provided you are performing an installation on the original directory structure on the original machine, and the directory contains no data or state information.
For information and examples on how to use the Java run time library API’s to license protect your Java application, see the Java ISV Application Development Guide. For specific information on using the Java run time library API’s, see the Java Run Time Library API Reference Java documentation. 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.
If you are integrating automatic key generation into your Java servlet or JSP based eCommerce web site, see the Java eCommerce Application Development Guide for information and examples. Specific information on using the key generation API’s is available in the E-Commerce License Key Generation API Reference Java documentation.