i4admin(1M)

NAME

i4admin — administer LicensePower/iFOR licensing

SYNOPSIS

i4admin [-Standard-X-Arguments]

i4admin -a [-n server-name] [-f filename] [-v "'vendor-name' [vendor-id vendor-password]" -p "'product-name' 'product-version' license-password ['license-annotation']"]

i4admin -d [-n server-name] -v vendor-name -p product-name -t timestamp

i4admin -l s|v|p [-i] [-n "server-name..."] [-v "'vendor-name'..."] [-p "'product-name'..."] [-u "user-name..."]

i4admin -s [-n "server-name..."] [-v "'vendor-name'..."] [-p "'product-name'..."] [-u "user-name..."]

i4admin -r 1|2|3|4|5 [-e 1|234567] [-b start-date] [-g end-date] [-n "server-name..."] [-v "'vendor-name'..."] [-p "'product-name'..."] [-u "user-name..."]

i4admin -x before-date -n "server-name..."

i4admin -h

DESCRIPTION

The LicensePower/iFOR Administration tool, i4admin, completely manages the LicensePower/iFOR licensing system. The tool can perform the following tasks:

Perform basic license administration (e.g., adding and deleting licenses).
Construct a single logical view of the license system from which current summary license usage and current detailed license usage reports can be generated.
Generate detailed license event and license usage reports from logged server data.

The i4admin tool has a Graphical User Interface (GUI) and a Command Line Interface (CLI). If i4admin is invoked with non-X arguments, the CLI version is started, otherwise the GUI version is started.

A printable on-line administration guide is also available. (See the FILES section below.)

CLI Actions

The CLI is invoked with one of the following actions, and one or more action modifiers.

-a

Add a product license to a specified license server. There are two ways to add a license to a license server.

If the license information has been provided in the form of a license certificate (a flat file describing the license), the license certificate can be added by specifying the server-name and the license certificate filename. If the server name is omitted, the license is added to the license server running on the local machine.

If the license information has not been provided in a license certificate, the parameters must be entered individually. All three vendor parameters are not always required. If the vendor for the product is already installed on the server, only the vendor-name must be specified, otherwise the vendor-name, vendor-id and vendor-password must be specified.

-d

Delete a product license. To delete a compound password, or a use-once license, the license must have expired. If the server name is omitted, the license is deleted from the license server running on the local machine. The license timestamp must be specified to differentiate between licenses for the same product (same Vendor ID, Product ID, and Product version), which are installed on the same server. The license timestamp can be found using the list product details command:

i4admin -lp -i -p product-name

-l

List installed license information. The command is qualified by the list type flag, s|v|p, to list servers, vendors, or products respectively.

The vendor list can be limited to specific servers by entering one or more server-names. If more than one server-name is entered, the list must be enclosed in double quotes.

By default the product list contains a summary of product information. Detailed product information can be queried by specifying the -i parameter. The product list can be filtered by server, vendor, and user. If more than one vendor-name is entered, the list of vendor-names must be enclosed in double quotes. Any vendor-name which contains white space must also be enclosed in single quotes.

Specify one or more user-names to limit the product list to products currently in use by the those users.

-s

Generate a status report containing detailed current license usage. For each product, the report includes the number of licenses in use, the user of the product and when license was acquired. By default the status report is generated based on all active license servers in the cell. The scope of the report can be limited by specifying server-names, vendor-names, product-names, or user-names.

-r

Generates reports which are based on license events logged by the license server. The command will generate one of five reports specified by the report-type flag (1|2|3|4|5).

1: Reports server log events. This command is further qualified by the event-flag which is described below.
2: For each product lists the number of requests for licenses, the number of licenses granted, and the percent of rejected requests.
3: Lists the same information as 2 but breaks out a separate entry for each user.
4: For each product, lists the maximum concurrent nodes, maximum concurrent users, and average time in use.
5: For each product, lists the number of times each user invoked the product and the average time the product was in use.

-x before-date

Delete all log entries on the servers specified by server-names which are timestamped on or before before-date

-h

Display a synopsis of command-line options

CLI Action Modifiers

-b start-date

Specify the start date for generating log reports. By default the start date is Jan. 1 1970.

-e event-type

Specify an event filter for the standard event report (-r1). By default all events are listed.

1: All events (default)
2: License related events (license request, license release, etc.)
3: Vendor messages
4: License database modifications (license added, license deleted, etc.)
5: Error events (license request failed, vendor not found, etc.)
6: Server start/stop
7: Fatal error events (server out of memory, server file IO error, etc).

Error events 2-7 can be combined, e.g., -e357 to list vendor messages, error events, and fatal error events.

-f filename

Specifies filename for adding a license certificate.

-g end-date

Specify the end date for generating log reports. By default the end date is current day.

-i

Include license details (start date, end-date, multi-use rules, timestamp, etc.) when listing products.

-n "server-name..."

Specify a server when performing administrative actions (adding a license, deleting a license, cleaning the log file), or limit the scope of a listing, status report or event report to a particular server, or servers. If more than one server-name is specified to limit the scope of a listing or report, the entire argument must be enclosed in double quotes.

-p "'product-name' 'product-version' license-password ['license-annotation']"

Specify a product when adding a license (-a) which is not defined in a license certificate. The entire argument must be enclosed in double quotes. If the product-name, product-version, or license-annotation contains white space the argument must be enclosed in single quotes.

-p "'product-name'..."

Specify a product, or products to limit the scope of a product listing (-lp), a status report (-s), or a event report (-r). If multiple product-names are specified, the entire argument must be enclosed in double quotes. If any product-name contains white space it must be enclosed in single quotes to differentiate the argument from multiple single-word product names.

-u "user-name..."

Limit the scope of a status report, or event report to a specific user, or users. If more than one user is specified, the entire argument must be enclosed in double quotes.

-v "'vendor-name' [vendor-id vendor-password]"

Specify a vendor when adding a product license manually. If another product for this vendor has been installed on an active license server in this cell, only the vendor-name must be specified. If a product for this vendor has not been previously installed on an active server in this cell, the vendor-id and the vendor-password must also be specified.

GUI Description

The i4admin GUI provides an intuitive dialog based interface to manage all aspects of the LicensePower/iFOR licensing system. The main window is divided into four functional areas:

The menu bar contains pulldown menus which provide the interface to all administrative commands.
The toolbar provides direct access to frequently used commands.
All reports are displayed in the scrolling display area.
When performing a task, the tool displays its progress in the status line at the bottom of the main window.

The GUI tool can perform the following tasks which will be described in detail in succeeding sections.

Basic license administration which includes adding and deleting licenses.
Extensive report generation based on current license usage and logged license events.

GUI Administrative Tasks

The Administrative tasks are adding licenses, deleting licenses, and cleaning up stale licenses. There are two ways to add a license. If the license information has been provided in the form of a license certificate (a flat file describing the license), follow the first procedure. If the license information has been provided in any other form, follow the second procedure.

Adding a license from a license certificate

1.: Open the Add pulldown menu and select the License... menu item.
2.: Select the server to add the license to from the Server drop-down listbox.
3.: Select the Read certificate... button.
4.: Enter the name of the license certificate in the Selection entry field. The Filter entry field and the Filter button can be used to limit the selection to a specific file or range of files.
5.: Select OK to accept the file selection and close the dialog. Verify that the Vendor name, Product name, and Product version appear correctly on the Add License panel.
6.: Select OK to add the license to the selected server and close the Add license dialog.

Adding a license manually

1.: Open the Add pulldown menu and select the License... menu item.
2.: Select the server to add the license to from the Server drop-down listbox.
3.: Select the Enter manually... button.
4.: Select the product's vendor from the drop down list of vendors which are displayed. If the product's vendor is not displayed, select the New vendor button to specify the vendor information.
5.: Enter the Product name, Product version, License password, and optional License annotation (if provided) in the fields.
6.: Select OK to accept the information and close the dialog. Verify that the Vendor name, Product name, and Product version appear correctly on the Add license dialog.

Deleting a license

1.: Change to the Product details view. To change views select the desired view from the View pulldown menu.
2.: Select a license to delete. Note that selected items which can be acted on are distinguished from plain text by the highlight color of the selection.
3.: Select Delete license button from the Selected pulldown menu. The tool will ask for confirmation before deleting the license. Note that compound passwords, and use-once licenses cannot be deleted before their expiration date.

Cleaning up stale licenses

When a client application acquires a license from the license server, it also periodically checks back with the server to tell the server the application is still running. The interval between checks is referred to as the check-in period. The server does not automatically release licenses for applications which have missed their check-in period. However, if a client application attempts to acquire a license and none are available, the server will check all the outstanding licenses to make sure the respective clients have checked in. If a client has missed its check-in period, that client's license will be granted. The clean stale license command forces the server to iterate through the outstanding licenses, releasing the licenses which have not been checked.

To clean up stale licenses for a product or products:

1.: Select one or more products from the Product summary view or the Product status view. Multiple entries can be selected by holding the Shift or Control key down while selecting.
2.: Open the Selected menu and choose the Clean stale licenses menu item.

GUI Usage and Installed License Reporting

This set of reports are generated based on installed license details, and current usage information. The reports are generated based on a snapshot of the license system at a particular instant in time. Since the license system may be constantly changing, the information contained in these reports is only as current as the last snapshot.

These reports contain information which is summed across the license system. The i4admin tool constructs a single logical view of the license system from which these reports are generated. This logical view is referred to as a snapshot of the license system. There are three reports based on the snapshot. The reports are accessed via the View pulldown menu.

The product summary is a terse view of a product's installed licenses and current license usage. >From this view the administrator can quickly identify problem areas, i.e., a product has 10 licenses installed, and 10 are in use.
The product details view reports detailed installed product information, including the number of license installed, the start and expiration date of the licenses, and the server that the license is installed on. >From this view, the administrator can select delete a license.
The product status view generates a detailed current usage report which includes; the number of licenses installed, the number of licenses currently checked out, who is using the license from what node, and how long the user has had the license.

By default these reports are based on all the installed products and licenses on all the servers contained in the current snapshot. The scope of any of these reports can be limited by applying one or more View Filters. The View filter allows the report to be scoped by server, vendor, product, or user. To change the View filter:

1.: Select Filter... from the View pulldown menu.
2.: From the View filter dialog select the type of filter to apply.
3.: Select OK to close the individual filter selection dialog. Select OK to close the View filter dialog. The view will be immediately updated based on the new view when the View filter dialog is closed.

It is important to remember that these reports are only as current as the last snapshot. The snapshot can be updated manually or automatically.

To update the snapshot manually, select Refresh now from the Snapshot pulldown menu. The snapshot will be immediately updated,

To update the snapshot automatically, open the Automatic refresh dialog from the Snapshot pulldown menu. Select the Automatic refresh radio button, and enter a refresh interval in minutes.

GUI License Event Reporting

These reports are generated by querying information directly from a server or servers. Since the amount of logged event information may be extensive it is impractical to create a local snapshot of all the log information to generate reports from.

The reports can be filtered using the same View Filter as previously discussed. A log report can be scoped by server, vendor, product, or user. By default, the View filter dialogs allow the administrator to select from the servers, vendors, products, and users which are contained in the current snapshot. If the desired filter item is not contained in the current snapshot, the administrator can manually specify the name in an entry field on the filter dialog.

There are five log reports which are summarized below.

License event log reports which reports logged server events without deriving additional information. There are seven categories of events which can be included in this reports.
1.
All events
2.
(default) License related events (license request, license release, etc.)
3.
Vendor messages
4.
License database modifications.
5.
Error events (license request failed, vendor not found, etc.)
6.
Server start/stop
7.
Fatal error events (server out of memory, server file IO error, etc.)
Note that error events 2-7 can be combined.
License requests by product. For each product lists the number of requests for licenses, the number of licenses granted, and the percent of rejected requests.
License requests by user. Lists the same information and the previous reports, but breaks out a separate entry for each user.
License use by product. For each product lists the maximum concurrent nodes, maximum concurrent users, and average time in use.
License use by user. For each product, lists the number of times each user invoked the product and the average time the product was in use.

AUTHOR

i4admin a product of Isogon Corporation.

FILES

/opt/ifor/ls/conf/i4rpt.fmt: Report templates
/opt/ifor/ls/res/*.bmp: Icon bitmaps
/opt/ifor/ls/res/i4admin.pdl: Panel definitions
/opt/ifor/ls/doc/i4admin.pdf: LicensePower/iFOR Administrator's Guide (Adobe Acrobat format)
/opt/ifor/ls/doc/i4admin.ps: LicensePower/iFOR Administrator's Guide (postscript format)