License Manager User Guide
Composing And Generating Keys From Scratch
Selecting License Model And Type
Cloning Keys Based On Existing Keys
Exporting Customer / Product / Key Data
Importing Customer / Product / Key Data
Managing The EasyLicenser Product License
Backing Up The EasyLicenser Configuration
Restoring The EasyLicenser Configuration
When you log on to EasyLicenser, you are presented with the main screen, which is organized to support the primary activity: generating and managing keys for a selected product and end customer. 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 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 your license to a new installation.
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 define and maintain information on 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 and incrementally generating replacement keys.
EasyLicenser License Management
Managing the EasyLicenser license consists of viewing the details of your license to use EasyLicenser, registering EasyLicenser with Agilis, and adding to your license quota or otherwise updating your EasyLicenser license.
Obtaining Help
The help menu launches a 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. If EasyLicenser detects a default web browser on your machine, it is used. Otherwise, EasyLicenser's built-in browser is launched.
You can also directly launch a traditional browser such as Internet Explorer or Netscape to view the help information without running EasyLicenser. 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 customers 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 may be used to enter any information associated with the customer.
Other than the customer name, all fields are optional and may be filled in later as more information becomes available.
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:
(a) 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:
(b) 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 its parameters, and another for defining the available options for the product:
The password field is optional. If specified, keys that are subsequently generated based on the product will be access controlled. That is, your application developers will specify a corresponding password public key to the license key checking API calls in the application code. The password public key is automatically generated by the GUI. It is visible when you view the product details after completing the creation process, through the Products..Details menu command. You should disclose the password public key only to your developers.
The Add Orion Server Options button is a short-cut to automatically define all the options used to control the configuration of the Orion network license server for Orion server license keys that are generated based on this product. The network license options that are added all have their names prefixed with ILS:. Their meaning and purpose are discussed at length in the Orion product documentation, which you will have if you need to generate floating license keys and / or product activation license keys for the Orion server. Note that Orion licenses can have normal user-defined options as well. The user-defined options are visible to the Orion-enabled application, which does not have access to the Orion-internal options.
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. 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. Values in the list may use any 7-bit US ASCII characters other than ';'.
The process of composing and generating a batch of new 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 only contain 7-bit ASCII characters.
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 does not 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
You can select between User/Orion and Server license models:
Note that the Server license model is for server applications that are license protected with the EasyLicenser runtime libraries, rather than for Orion-based applications. For Orion server licenses, select User/Orion.
Associated with the User license model, you can choose between Named User, Machine and (if enabled for network licensing) Orion server licensing:
If you select User or Machine, you are accordingly prompted for a unique user or host name:
If you select Orion Server License, you are prompted for additional information pertaining to the Orion server license:
You are asked to enter a license server host name, an Orion user limit, and a license server service name that defaults to default. The license server host name is specified in exactly the same way as the host name specification for machine and server licensing, described below, or as a combined user/host specification as for user licensing, described below. If operating system level node locking is not required, the default "network" name may be used. The meaning of the remaining fields is described in detail in the Orion product documentation.
If you select the Server license model, you can choose between Named Role, 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. This is the information that is reported by 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, this corresponds to the output obtained from running the "hostname" or equivalent command. On Windows, pressing CTRL-ALT-DEL as above will provide the machine name information.
With both user and server licensing and operating-system enforcement, you also have the option of enforcing both a user name and a machine name, by specifying the user / host name with the following syntax:
user@machine
For example: root@linuxmachine
This is equally applicable to the license server specification for generating floating license keys.
Whether or not the machine name is qualified with a domain name depends on the specific operating system and network configuration. However, so long as the procedures described above and below are followed, this is transparent to the end user and to you provided there are no subsequent changes to the logical network topology.
EasyLicenser includes a ezlicmgrmcinfo command line utility that can be redistributed to end customers to simplify the process of obtaining node locking information. The utility accepts parameters that control whether just the machine name or the combination of username and machine name are introspected and reported in the appropriate syntax for key generation. Using this utility, it is unnecessary for your end customers to manually run the above operating system commands.
When specifying operating system level node locking information, the accompanying Enforce Operating System Check checkbox is also checked.
Specifying License Parameters
There are three types of license parameters, organized into a tabbed pane.
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 character ';'.
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. The special character ':' is implicitly translated to '|' for storage. 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.
Orion server license keys are internally processed by the Orion network license server rather than your application. Accordingly, the advanced tab is unavailable when generating Orion server keys, and its contents are created internally for use by the network license server itself.
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 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 or machines. 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.
If the generated keys are not published, they remain in a selected state in the work area. If a subsequent key generation is performed, the previous batch of such selected unpublished keys is deselected and not included for subsequent publishing.
Managing Keys In The License Key Work Area
The license key work area is initially populated with all keys associated with a selected customer and product. As additional keys are generated, these are added to the work area. In essence, the work area is a contextual equivalent to the more general key management screen that is navigated to from the Licenses .. Manage menu command, with keys filtered for the selected customer and product.
You can manipulate the keys in the work area 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 or if you know the identity of the creator.
Once in the Key Details screen, you can incrementally generate a clone of the key, as described below.
You can create a clone of an existing key with incremental modifications, by first using the key details of the original key and then enabling cloning by clicking the Enable Cloning checkbox.
There are two types of cloning:
Basic cloning: generate a key that is similar to an existing key, but possibly with some differences in the key parameters, for example a different customer name or license limit. With the exception of internally- generated or anchor values such as creation date, creator identifier and product information, there are no significant restrictions on what parameters can be changed. The key details dialog box that is presented when basic cloning is enabled is illustrated below:
![]()
Chaining: generate a key that is linked to the origin key, possibly with some restricted differences in the key parameters, for example a different expiration date or concurrent user limit, such that the chained key can only be used to replace the original key at an end customer installation. Chaining is applicable only for keys generated for the Orion server.
Chaining is enabled by also clicking the Enable Chaining checkbox. The key details dialog box that is presented when chaining is enabled is illustrated below:
![]()
Only a single key is generated as a result of cloning (by clicking the Generate Cloned Key button) or chaining (by clicking the Generate Chained Key button). Upon generation of the key, you are presented with a dialog box for the purpose of publishing the key. You can dismiss the dialog box if you don't want to publish the key just yet. Regardless of whether or not you publish the key, it is saved in the license key repository for later retrieval and publishing.
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 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.
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.