IBM Support

How to install and configure the License Manager Server for Host On-Demand and Personal Communications

Question/Answer


Question

How to install and configure the License Manager Server for IBM Rational Host On-Demand and IBM Personal Communications?

Cause

The License Manager Server Document is not included in the Knowledge Center as it is not tied to any specific product and also because it is new for Host On-Demand (HOD) 11.0.11, Personal Communications (PCOMM) 6.0.12, and HOD Toolkit 11.0.11 [that contains the Host Access Client Library (HACL) APIs for customer-written applications].

Answer

License manager is a tool that facilitates effective software management between end users and software vendors, that allows the organization to track and document the usage of the company's software products. IBM Host Integration License Manager is the license control tool specifically used for tracking the license information for the Mainframe Terminal emulator products like IBM Host On-Demand and IBM Personal Communications.

The Host Integration License Manager can be configured with the following versions of IBM Terminal Emulators :

* HOD 12.0.0.0 & above

* HOD 13.0.0.0 & above

* PCOMM 12.0.0.0 & above

* PCOMM 13.0.0.0 & above

 

Host Integration License Manager (LM) when installed and configured with WebSphere Application Server (WAS), can track license usage for both HOD and PCOMM

Prerequisites for the installation of License Manager:

* WebSphere Application Server v8.5 and above

Installation Steps:

To install License Manager, follow the steps below:

1. Download the zip file from  Fix Central or from Passport Advantage for HACP v12 or v13 as a separate product
2. Extract the zip file into any folder
3. Install the .ear or .war file on the application server by following the deployment instructions for the respective application server
4. Enter the URL (refer to the example below) to access the License Manager Web application: 

http://<appserver-address>:<port-num>/<context-root>

where, <appserver-address> is the hostname or IP address of the server on which license manager is installed, <port-num> is the port that is specified during the deployment of the application server and <context-root> is the location name that can be configured by the Administrator.


Steps to configure License Manager:
 

For HOD:

For all the client types (Cached Client, Download Client and Webstart client) and Programmable HOD, add the following parameters to the configuration file, (config.properties) that is located in the HOD server publish directory.

  • licenseserverurl = License Logger URL – <appserver>:<port>/<context-root>/LicenseLogger
  • timeout= Logging request interval (in mins) after which the server marks the client as timed out if the request is not sent. Minimum value is 5 and maximum value is 30.
  • enableMacAddress = set true to enable mac address logging, default value is false.
  • enableMachineName = set false to disable machine name logging, default value is true.

 

For example:

licenseserverurl=http://127.0.0.1:9080/LicenseManager/LicenseLogger

timeout=5

enableMacAddress=true

 

For Configuring Workplace Client Technology (WCT) client pages, the same parameters should be added as HTML parameters using the Deployment Wizard.

Name: licenseserverurl
Value: http://<server-address>:<server-port>/<context-root>/LicenseLogger
Name: timeout
Value: n (where n = 5 to 30 [minutes], Default value = 5)
Name: enableMacAddress
Value: true or false, default is false

 

For Configuring Host Access Client Library (HACL) applications, developers can set the License server URL and timeout values with the below session parameters and statements:


p.put(Session.LICENSE_SERVER_URL,"http://<server-address>:<server-port>/<context-root>/LicenseLogger");
p.put(Session.LICENSE_SERVER_TIME_OUT,"5");
p.put(Session. LICENSE_SERVER_MAC_ADDRESS,"true");
p.put(Session. LICENSE_SERVER_MACHINE_NAME,"false");

 

For PCOM:

Add the following parameter values to the pcswin.ini file, typically located in the License section of the file as below:

C:\Users\<userID>\AppData\Roaming\IBM\PersonalCommunications

URL = http://<server-address>:<server-port>/<context-root>/LicenseLogger
Interval = Logging request interval (in mins) after which the server marks the client as timeout if the request is not sent. Minimum value is 5.

 

For example:
[License]
URL=http://127.0.0.1:9080/LicenseManager/LicenseLogger
Interval=5

 

IBM Personal Communications supports both HTTPS and HTTP connections to the License Manager.

In an intranet environment, when a License Manager Server is configured with local Certificate Authorities, if an error occurs while verifying the certificates received from the license manager, the HTTPS connectivity from PCOMM client to the license manager may also fail. Following keywords have been introduced into the pcswin.ini file to handle this:

 

[License]
IgnoreUnknownCA=Y
IgnoreInvalidCertCN=Y
IgnoreCertRevCheck=Y

When IgnoreUnknownCA is set to Y, it allows an invalid certificate authority. This allows PCOMM to send License information even when the License Manager Server sends an untrusted CA. This setting is recommended only under test environments. The default value of the keyword is set to N.
When IgnoreInvalidCertCN is set to Y, it allows an invalid common name in a certificate; that is, the server name specified by the application does not match the common name in the certificate. This setting is recommended only under test environments. The default value of the keyword is set to N.
When IgnoreCertRevCheck is set to Y, it ignores certificate revocation problems. This allows PCOMM to send License information even when it could not verify whether the host certificate is valid or revoked. This setting is recommended only under test environments. The default value of the keyword is set to N.

 

Please note that these keywords are recommended only under test environments.

Also, the following keywords in the .ini file have been provided to enable or disable IBM Personal Communications emulator sessions from sending the MAC Address and machine name to the HI License Manager Server. The keywords are part of the License section of the pcswin.ini file.

 

[License]
enableMacAddress = N
enableMachineName = Y


When enableMacAddress is set to N, the license manager server log shows MAC_ADDRESS_DISABLED under the MAC ADDRESS column. The default value of the keyword is set to N.

When enableMachineName is set to N, the license manager server log shows MACHINE_NAME_DISABLED under the MACHINE NAME column. The default value of the keyword is set to Y.


Using the License Manager:

After the server module is successfully installed, administrators can use the license logger to monitor the client login from the License Manager admin console.

The console can be accessed by navigating to:  
http://appserver-address:port-num/<context-root>/

When prompted for username and password, user can login with the default username admin and password password.

image-20180831145603-1

After logging in as the License Manager Admin, you can change the password by clicking on “admin on the menu bar. Refer to the ”Create New User" and "Change User Password"  sections below for more information.

image-20180831145648-2

As a License Manager administrator, you can perform the following tasks:

 

  • Manage users who can access the administrator console
  • Configure the number of licenses
  • Monitor the number of users currently active
  • Configure the log settings
  • View or download the log files

    To configure the number of licenses, follow the below steps:
  1. Click Home on the menu bar.
  2. Enter the maximum licenses.
  3. Click Save.

 

image-20180831145729-3

---------------------------------------------------------------------------------------------
License Information:
---------------------------------------------------------------------------------------------

Number of licenses purchased
Allows user to specify the maximum license count. Default value is set to 1 as the maximum count. User is allowed to change the default value and specify the required maximum license count. When " Active license" count crosses the maximum limit specified, a warning message is shown indicating this.

Total active licenses
Number of active concurrent licenses for both HOD & PCOMM combined.

---------------------------------------------------------------------------------------------
License Count Statistics
---------------------------------------------------------------------------------------------
Highest Concurrent License Count
Highest concurrent license count gives the maximum number of distinct users who have accessed the product (HOD/PCOMM) simultaneously, since the installation of License Manager.

 

Highest Authorized License Count
Highest authorized license count gives the maximum number of authorized users who have accessed either of the products (HOD/PCOMM) on a day.

Cumulative Authorized License Count
Cumulative Authorized License Count gives the total number of distinct authorized users who have accessed either of the products (HOD or PCOMM) till date, since the installation of License Manager.


More
Clicking on the More option, takes us to the License Summary Report for both the products combined.

By default, the report shows a daily summary of the licenses for each of the products HOD, PCOMM and HACP. The filter feature can be used to view the license usage for a specified date interval. It includes the following information for HOD, PCOMM and HACP.

  • Highest Concurrent License Count (MM-DD-YYYY)
  • Highest Authorized License Count (MM-DD-YYYY)
    The tabular view shows the following license details for HOD, PCOMM and HACP with time stamp.
  • Highest Concurrent License Count
  • Highest Authorized License Count
  • Cumulative Authorized License Count
    The Admin can sort and customize the report to include/exclude specific columns as required.

 

image-20180831145830-4

---------------------------------------------------------------------------------------------
HOD and PCOMM Specific License Count Statistics
---------------------------------------------------------------------------------------------

 

image-20180831150344-6

 

 

Each section/tab provides the following information for the specific product.

 

  • Active Licenses
  • Highest Concurrent License Count (Today)
  • Highest Concurrent License Count
  • Total Authorized Used License (Today)
  • Highest Authorized License Count
  • Cumulative Authorized License Count

 

Active Licenses
Active concurrent licenses for HOD/PCOMM (for the active sessions). Admin can view the active client details by clicking the highlighted Active Licenses link. Active clients report shows the below information about all active clients at that time.

  • IP Address
  • System Username
  • Machine Name
  • MAC Address
  • Sub-Client Type
  • Check-In-Time

 

The Admin can sort and customize the report to include/exclude specific columns as required.

Highest Authorized License Count
Highest Authorized license count gives the maximum number of authorized license users accessing the product (HOD/PCOMM) on any day since the installation of License Manager.

Cumulative Authorized License Count
Cumulative Authorized license count of distinct authorized users since the installation of license Manager for the product (HOD and PCOMM).

Create new log files daily
The check box below can be enabled, to generate a new log file every day. Older log files are saved with their time stamp as a backup. (By default, this box is unchecked)

 

 image-20180831150434-8               

 

The client reports that are generated, are automatically sent to the Licensing server at regular time intervals. The client reported log entry (.csv file) is maintained in a file under the respective client directory (HOD or PCOMM).

 

Log file size
This field is enabled only when "Create new log files daily" option is disabled. By default, this field is enabled. Specify the maximum size (in MB) of the log file. A new log file is created when the current log file exceeds this maximum limit. By default, the Log File Size is set to ‘0’ (i.e., the log file will be created without a size limit).

Number of log files
Field gets enabled only when some value is provided in "Log file size" field. By default, this field is disabled. When the number of files exceeds the limit, the existing log files get over-written.

 

---------------------------------------------------------------------------------------------
License Usage Details
---------------------------------------------------------------------------------------------
License details report for the current day (HOD and PCOMM).

Log level

This option is available on "License usage details" page. Select the log level (from 1-LOW to 3-HIGH) to filter the number of entries to be logged. The default log level, Level 3 (HIGH), logs all the entry parameters, including connection closed entry as well as the periodic client check-ins. All the other log levels (1 and 2) will log only the first client check-in and the connection closed entry. Following are the parameters which are logged:

  • IP Address of the client
  • System User name
  • Machine Name
  • MAC Address
  • Client Type
  • Status of connection
  • Timestamp

 

image-20180831150855-9

Level 3: All Parameters
Level 2: Timestamp, IP, System User Name, Client Type, Sub-Client Type, Machine Name, Connection Status   

Level 1: Timestamp, IP, System User Name, Client Type, Sub-Client Type, Connection Status
 

The license usage report containing Log level 3 (HIGH) with license usage information can be extracted by the Admin into a .csv file (that can be opened as an Excel Workbook). In case of a WebSphere Application Server, the default location of the downloaded log file is below:


C:\Windows\System32\config\systemprofile\LicenseManager
 

Default location may vary based on the application server configured for license manager.
To change the default location for log files for a WebSphere Application Server, follow the steps that are mentioned below.

 

  • Login to WebSphere Application Server
  • Go to Applications
  • Click WebSphere enterprise applications under Application Type
  • Click License Manager .war file
  • Click Initialize parameters for servlets link under Web Module Properties section
  • Specify required log file path under Directory Location  
  • Save the changes

    When "Create log files daily" option is not selected (disabled), multiple log files are listed on "License usage details" page. Admin can view the required log file by clicking on a link to the required file. Admin has an option to download all the log files as an archive file by clicking "Download All" link. Admin has an option to sort the report based on any given column.
    Form Controls:
    Refresh: Refreshes all the data on the Home page.
    Save: Saves all the configuration.

 

image-20180831150933-10

To manage users who can access the License Manager Admin console, click on Users on the menu bar.

 

image-20180831150956-11

---------------------------------------------------------------------------------------------
To Create New User
---------------------------------------------------------------------------------------------
To create a new user, follow the below steps:  

  • Go to Users tab
  • Specify the Username (username is not case sensitive)
  • Specify the required password (password length must be between 5 to 20 characters).
  • Re-enter the password in the Confirm Password box.
  • Click Submit      
    Note: New users for license manager can be created only by the Admin.

 

---------------------------------------------------------------------------------------------
To Delete an Existing User
---------------------------------------------------------------------------------------------

Under the Existing Users section, there is an option to delete the existing user, by selecting the icon image-20180831153902-1 next to the username.

---------------------------------------------------------------------------------------------
To Reset the Password for an Existing User
---------------------------------------------------------------------------------------------

If required, Admin can reset the password for a selected user to the default password (‘password’), by clicking on icon image-20180831155312-2 next to the username in the existing users list.

---------------------------------------------------------------------------------------------
To Change User Password
---------------------------------------------------------------------------------------------
User can change the current password, by hovering the mouse pointer over the Username field displayed on top of the screen. After specifying the current and new password, Click Submit.

 

Limitation: No National Translation is available, help files are available only in English.

 

 


Cross reference information
Product Component Platform Version Edition
Personal Communications
Rational Host On-Demand

Document information

More support for: Rational Host On-Demand

Component: Documentation

Software version: 12.0.0, 12.0.0.1

Operating system(s): AIX, Linux, Windows, iOS, z/OS

Reference #: 1691875

Modified date: 03 September 2018