Click to go to home page

License Manager User Guide


License Manager Layout

File Management

Edit

Product Management

Customer Management

License Key Management

EasyLicenser License Management

Obtaining Help

Defining A Customer

Defining A Product

Composing And Generating Keys From Scratch

Allowed Character Set

Choosing Customer / Product

Selecting License Model And Type

Specifying License Parameters

Specifying Key Generation Criteria

Generating Keys

Managing Keys In The License Key Work Area

Managing Customers

Managing Products

Managing Keys

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

Next Steps


License Manager Layout

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.

Defining A Customer

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.

Defining A Product

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 ';'.

Composing And Generating Keys From Scratch

The process of composing and generating a batch of new keys consists of performing the following steps in that order:

  1. Choosing the product and customer for which the keys will be generated.
  2. Selecting the license model and type, and providing the appropriate parameters for user or host name.
  3. Specifying the license parameters and determining whether to enforce an operating system check.
  4. Specifying the key generation criteria.
  5. Generating the keys into the license key work area.
  6. 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 to generate backward compatible keys that will work with older versions of the EasyLicenser runtime library, 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, initially in a selected state.  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. Otherwise, they are deselected as they are published.

Managing Keys In The License Key Work Area

Population

The license key work area is initially unpopulated. When you choose either a customer or a product in the customer / product selection area, the work area is populated with all keys associated with the selected customer or product, initially in an unselected state. If you choose both a customer and product, only the keys matching the product and customer are displayed. 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 / or product.

Publishing batches of license keys for multiple products

A common use case is a scenario where you may want to generate multiple keys for a given customer but for multiple different products, then publish all the generated keys in a single file for delivery to the customer. The license key work area accommodates this use case by not filtering keys based on the selected product if at least one key exists in the work area in a selected state. This enables you to select a product, generate keys based on it without autopublishing them (thus retaining the generated key(s) in the work area in a selected state), select the next product and generate additional keys, again without autopublishing the keys, until key generation for all products is completed, then click the Publish button to publish the accumulated keys in a single file.

Operating on keys

You can manipulate the keys in the work area individually or as a group as follows:

Managing Customers

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.

Managing Products

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.

Managing Keys

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. If the key's version is 2.6 or later, corresponding to keys generated in non-compatible mode using EasyLicenser 2.5.11 or later, an accurate version of the underlying product's definition is required to be available in the product database as well. At a minimum, the product definition is required to have the value for the application password and the corresponding public key that was in effect when the key was generated.

Once in the Key Details screen, you can incrementally generate a clone of the key, as described below.

Cloning Keys Based On Existing Keys

You can create a clone of an existing key with incremental modifications, by first obtaining the key details of the original key as described above, and then enabling cloning by clicking the Enable Cloning checkbox.

There are two types of cloning:


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.

Exporting Customer / Product / Key Data

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.

Importing Customer / Product / Key Data

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.

Managing The EasyLicenser Product License

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:

Backing Up The EasyLicenser Configuration

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.

Restoring The EasyLicenser Configuration

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.

Next Steps

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.


Copyright © 2002+ Agilis Software LLC, Santa Clara, CA, USA. All rights reserved.