Downloads |
 Feedback
|
Table Of Contents
Understanding CWCS Licensing APIs
Integrating CWCS Licensing APIs
Understanding License Framework
Using Licensing Framework With Applications
License File Format for Common Services 3.0
Using the Licensing APIs
The CWCS Licensing API allows you to:
•
Install and update licenses.
•
•
The following topics describe how to use the CWCS Licensing APIs with your application:
•
•
For basic information on the CWCS Licensing API, see the "About CWCS Licensing" section on page 27-6.
For more information on CWCS Licensing APIs, see:
•
•
•
•
Understanding CWCS Licensing
Software licenses are used to prevent unauthorized use of software products. Historical use of licensing technology in CWCS predecessor products included:
•
•
The current CWCS licensing:
•
•
•
The CWCS licensing framework supports the following features:
•
•
•
•
•
•
•
•
•
License models other than those noted above such as node-locked licenses, floating licenses, counted licenses, etc., will not be directly supported in CMF 3.0. Applications that require such features must use FLEXlm toolkit to implement a licensing model that meets their requirements.
Using Licensing UI
This topic provides information on the end-user interface of the License Information page:
To access the License Information page:
Step 1
The Admin page appears.
Step 2
The License Information page appears.
The License Information page displays the details of the available licenses.
To update a license:
Step 1
The Admin page appears.
Step 2
The License Information page appears with the details of available licenses.
Step 3
The Select License File popup window appears. The CWCS installation directory is displayed in the License File field.
Step 4
The Server Side File Selector popup window appears.
Step 5
Step 6
Step 7
The file must be a valid license file with read permissions for the user.
Step 8
Understanding CWCS Licensing APIs
The Licensing framework supports Java interface to install and retrieve license information. The licensing API supports the following operations:
•
•
•
•
•
•
•
•
License data would contain information such as the installation date, expiration date, license type, number of devices that can be managed, and PAK/PIN or license key(s) associated with the application.
CWCS Licensing Classes
The CWCS Licensing classes are:
LicensedFeature
LicensedFeature represents a feature or application that has license (such as RME), in addition to a name, version, expiry date and the number of licenses.
Instances of this class contains information on whether the feature has an evaluation, upgrade, purchased, or a special kind of license. Since feature licenses may be delivered via a FLEXlm license file or a PIN, instances of this class may also be queried for the source of licensing information.
The following table provides information on the methods used by LicensedFeature:
LicenseManager
LicenseManager helps applications to manage licenses. Applications based on CMF that need to enforce license restrictions must use this class to install and retrieve licenses.
The following table provides information on the methods used by LinceseManager.
LicensePAK
LicensePAK represents a PAK/PIN combination and the time at which the PAK/PIN was installed.
The arguments for this class are PAK and PIN associated with the license. The installation time of the LicensePAK is set to current time.
The following table provides information on the methods used by LicensePAK.
Error Codes Generated by APIs
The following table describes the error codes enerated by the API:
Integrating CWCS Licensing APIs
This section provides information on integrating the licensing APIs with your application.
JavaDoc
The Javadoc for the License API can be found at following URL.
http://nmtgre.cisco.com/auto/embueng/License/
License Installation
Licenses can be installed during the installation of a bundle, or at a later time.
The license installation UI does not appear during the Common Services 3.0 installation. The UI appears only for the first application in the bundle that is installed.
The application install code must verify the existence of a valid license for that application. If a valid license is missing, the application prompts to enter the license at the installation time.
If the first application installation contains a license key that has entries for all the applications in the bundle, subsequent application installations do not have to prompt for licenses.
•
•
•
•
Version of the FLEXlm libraries : Version 9.2
PAK and PIN
PAK and PIN are processed in pairs—while the PAK carries no information that is useful to CMF, a PIN is associated with a product or an application, and encodes the type of license (evaluation, upgrade, or purchased) the user has for that product.
1.
2.
–
–
3.
4.
Since cases 2 and 3 can be potentially destructive, the user is warned, that continuing with the installation may render the product unusable, and the user should be given the option to cancel the installation. If the user proceeds with the installation, the License Framework will process all the license keys, PAKs and PINs that were entered by the user. In the case of fully purchased licenses/PINs, the license will be installed and no further processing is required during product installation. In all other cases, the licenses will be maintained in a state where their use is permitted only after authorization by a product or application.
Note
Handling Multiple Licenses
Applications may be licensed as part of an application bundle or separately. It is important to determine the effect of installing a license for an application for which a license has already been installed. In the following section, a PIN that is not superseded by the license key it represents is treated the same as the license key. We consider the following cases here:
Installing an evaluation license over a previously installed license.
This operation is invalid and the new evaluation license will be ignored.
Installing an upgrade license over an evaluation license.
The upgrade license will supersede the evaluation license.
If a fully purchased license for a previous version of the application is installed, the installed license will be upgraded to the newer version of the application. Otherwise, the upgrade license will be considered incomplete and the application that uses this license will function in NAG mode.
For more information on Nag mode, see License Requirements Document, EDCS-295207.
Installing an upgrade license over a fully purchased license
If the upgrade license is for the same or an earlier version of the application, as compared to the existing one, the upgrade license will be ignored. If the upgrade license is for a more recent version of the application, the installed license will be upgraded to the newer version of the application.
Installing a purchased license over an evaluation license.
Purchased license is installed.
Installing a purchased license over a previously installed purchased license.
Increases the device count.
Since purchased licenses do not have an expiration date, the only effect of this operation is to increase the device count, if any.
For example, if an application had license for 1000 devices, and a new license with a device count of 500 is installed for the application, the number of licenses for that application increases to 1500 devices.
Interpreting PIN
PIN allows a customer to continue using the product and provide information to the licensing component before the actual license key is entered. PIN provides the following information to the licensing component:
•
•
•
•
PIN does not contain more information than the license key. The license key contains all information that the PIN contains, and more.
The PIN alone does not provide any useful information regarding application name, version, and device limit and installation type. Each application code in the PIN should have a mapping file to get it mapped with an application. To enable this functionality, the evaluation license of each application is used. The evaluation license of each image has the application name, version and associated application code. The application code in license file is matched with the application code in the PIN to get the details about the application.
The PIN is not a substitute for the license key. The main function of the PIN is to allow the customer to continue using the product in the absence of a license key. This is because very often the user installing the product is not the one who purchased the product and obtains the license key. However, the customer has to enter the license key to move the product from the nagging mode to the full function mode.
If the customer does not enter the actual purchased license key within 90 days, and if a PIN is entered at install time, the product will always function in a NAG mode. In NAG mode, after 90 days, if the PAK and PIN are present, NAG messages will start appearing. If the PAK and PIN are not entered, i.e. if the product is in EVAL mode, the product stops functioning after 90 days.
The customer can enter the license key at install time or using the desktop GUI. It is recommended that the customer enters the actual license key rather than the PIN at install time. The PIN is only a fallback mechanism.
PIN Format
The format of the PIN has been designed to encode all the information required by Common Services licensing. A PIN can encode license information for a bundle or an arbitrary collection of applications.
PIN specification:
•
•
Description of a bundle can be further broken down as follows:
•
•
•
•
•
•
•
•
•
Understanding License Framework
The Licensing framework provides a way for licensing the evaluation version. The FCS image can be used as both evaluation version and purchased version.
Applications that need to use the Licensing framework must get the application mapping code from CWCS marketing team. (The application code is unique for each application and version. For example, RME 4.0 has an application code 22). Each application must get a static evaluation license file from CMF team. (The static license file contains application code map for the application, and device limit for the Evaluation mode).
This static evaluation license file should be part of the applications image. This must be under <ApplicationImage>/disk1/eval/<AppName.lic> . This license file is used during install, if the user selects Eval mode or PIN/PAK mode. The purchased license is generated by SWIFT based on the serial number or PAK.
When an application is installed, the framework will check for available license in the repository based on the Application name, version, and Application code.
If a matching entry is found either in license file or PIN, the framework does not prompt for license details. Otherwise, the user is prompted for license details.
The license file or PIN is validated and the installation proceeds.
The license repository is NMSROOT/etc/licenses. When a new license is added, the information is added to the repository with .lic extension.
The PIN/PAK details are stored in pinpak.data file.
Flowcharts
License Key and PIN entry during installation:
License Key and PIN entry within a 90 day period after installation:
Using Licensing Framework With Applications
To use the Licensing Framework provided by CWCS, the application must modify the following sections:
Install
License install framework is part of ITOOLS.
To use the licensing install framework:
Step 1
Example: PRODUCT_INFO=rme 4.0
Note
Step 2
Step 3
The license file name should read: <application name>.lic
CW Home Page
Applications must verify the license type. If the license type indicates that the application is for non-revenue programs, the application should display the message "The product is not licensed for commercial use."
Examples of non-revenue programs: SEVT, NFR, NA
API Call for getting the license type for an application:
LicensedFeature.licenseType( )
The call returns the type of license for that application.
Runtime Calls
To query licensing details at runtime:
Step 1
import com.cisco.nm.license.client.*;
import com.cisco.nm.license.util.*;
Step 2
LicenseManager lm = new LicenseManager();
LicensedFeature licFeature = lm.getAllFeaturs("Appname", "Version");
Step 3
Note
License SDK
The License framework will include an SDK containing FLEXlm tools and documentation, so that the applications can implement licensing models other than the one supported by CMF. The SDK contains:
•
•
•
Data Architecture
Licenses, PINs and PAKs that are installed using the License GUI or API can be retrieved using the License API. No other specifications are made regarding the internal representation of the license data or the mechanisms used to persist such data.
License File Format
The license file format specified in MDC Core License Model Document, EDCS-153881 is used for licensing other bundle applications.
In addition to the file format supported in Common Services 2.2 (as described in EDCS-153881), a new license file format will be used to support the features in Common Services 3.0. Applications that intend to use the features described in this document are required to use the new license file format described in section License File Format for Common Services 3.0.
The license file has a fixed structure. Words in CAPITAL BOLD are key words, unique to FLEXlm. Words in Italics should be replaced by the actual data. Other wording should be there in order for FLEXlm to be able to parse the syntax.
VENDOR cisco
INCREMENT licenseInfo cisco 1.0 expirationDate uncounted \
VENDOR_STRING=DeviceLimit HOSTID=Any \
NOTICE=DemoLength SIGN=0
INCREMENT licenseUser cisco 1.0 expirationDate uncounted \
NOTICE=PAK HOSTID=Any SIGN=0
INCREMENT PIX cisco 1.0 expirationDate uncounted \
NOTICE=PAK VENDOR_STRING=DeviceLimit HOSTID=Any SIGN=0
INCREMENT IOS cisco 1.0 expirationDate uncounted \
NOTICE=PAK VENDOR_STRING=DeviceLimit HOSTID=Any SIGN=0
INCREMENT IDS cisco 1.0 expirationDate uncounted \
NOTICE=PAK VENDOR_STRING=DeviceLimit HOSTID=Any SIGN=0
INCREMENT C3K cisco 1.0 expirationDate uncounted \
NOTICE=PAK VENDOR_STRING=DeviceLimit HOSTID=Any SIGN=0The first INCREMENT is followed by the keyword licenseInfo to identify that this feature line will describe the general license information.
License File Format for Common Services 3.0
Common Services 3.0 uses a new license file format.
Sample license file for an evaluation license for CDOne 3.0:
INCREMENT cdone cisco 3.0 31-dec-2004 uncounted \VENDOR_STRING=<LicType>Evaluation</LicType><Code>ZZ</Code><Count>10</Count><CountType>Abso lute</CountType><XINFO>LMS30</XINFO> \HOSTID=ANY \NOTICE="<LicFileID>lms</LicFileID><LicLineID>0</LicLineID> \<PAK>dummyPak</PAK>" SIGN=48CCDF82DDF6Each application in the bundle is represented by an INCREMENT line that specifies the name and version of the application. The first line in the file describes the bundle itself and does not contain any information that is useful to the applications. In addition to the feature name and version, Common Services licensing uses the fields expiry date (set to 31-dec-2003 in this example) and VENDOR_STRING to store the information it requires.
Alternate License File Format
License files issued by Swift will employ an alternate license file format to represent license information. This format uses other FLEXlm license file fields as follows to represent the information stored in the VENDOR_STRING field in the format described in the previous section.
Sample license file for the alternate format:
SERVERVENDOR ciscoUPGRADE CDONE cisco 2.2 3.0 permanent 10 \VENDOR_STRING=<XINFO>LMS30</XINFO> \NOTICE="<LicFileID>lms</LicFileID><LicLineID>0</LicLineID> \<PAK>dummyPak</PAK>" SIGN=535525A647B6FEATURE RME cisco 4.0 permanent 1500 \VENDOR_STRING=<XINFO>LMS30</XINFO> \NOTICE="<LicFileID>lms</LicFileID><LicLineID>0</LicLineID> \<PAK>dummyPak</PAK>" SIGN=7078C85E40E8FEATURE DFM cisco 2.0 permanent 1000 \VENDOR_STRING=<XINFO>LMS30</XINFO> \NOTICE="<LicFileID>lms</LicFileID><LicLineID>2</LicLineID> \<PAK>dummyPak</PAK>" SIGN=52A22CF20DF4FEATURE CampusManager cisco 4.0 permanent 500 \VENDOR_STRING=<XINFO>LMS30</XINFO> \NOTICE="<LicFileID>lms</LicFileID><LicLineID>3</LicLineID> \<PAK>dummyPak</PAK>" SIGN=333AD18EF768
Proof-of-Purchase (POP)
Proof-of-Purchase (POP) will be obtained when you enter an upgrade license key. The customer will not be able to install a product if they have paid only for an upgrade license, unless the customer has got a the license for a previous version.
One way of ensuring that a customer has purchased a previous version of the product involves checking for the previous version installation CD. The customer will only be required to use a CD as a last resort, even in a case where the upgrade is done on a new machine and the previous version of the product is one another machine. If a CD check is ultimately needed, the licensing component must not require the user to remove a CD that is being used to install the upgrade, replace it with a CD for the previous version to do the POP, then reinsert the product upgrade CD.
The licensing component will perform a POP check by checking the license file of the previously installed version of a definitive product for which the upgrade license has been purchased.
Versions of applications that are not based on CS 3.0 such as RME 3.4, RME 3.5, DFM 1.1, DFM 1.2, Campus Manager 3.2, and Campus Manager 3.3 have license files to help implement the CMF-style licensing. These files are called rme.xml, dfm.xml and cm.xml respectively for RME, DFM and Campus Manager respectively. These files contain an EXPIRY line with two possible values: NEVER (for purchased license) and 90 (for an evaluation license).
One application per bundle will be used to identify which bundle the customer had purchased. The following table shows what needs to be checked per bundle:
In-Place Upgrade
Install can automatically check for Proof-of-Purchase if the customer enters an upgrade license key or PIN, the proof of whether the customer has a purchased previous version is available immediately from the installed version.
Remote Upgrade
Install must prompt for Proof-of-Purchase. If the customer enters an upgrade license key or PIN, the proof of whether the customer has a purchased previous version must be verified.
•
At the end of installation, a message similar to the one below is displayed:
You have entered an upgrade license key. Please run the program <NMSROOT>/bin/validate_upgrade.exe to validate that this is an upgrade.
Until the user runs the above program, the product will run in NAG mode.
•
At the end of install, a message similar to the one below will be displayed:
"You have entered an PIN and not a license key. The product will continue to work in nag mode from the date of installation. However, please obtain a valid license key from CCO in order to make the product fully functional.
After obtaining the license key, load it into CiscoWorks by clicking on: Common Services > Server > Admin > Licensing.
After entering the license key, please run the program <NMSROOT>/bin/ validate_upgrade.exe to validate the upgrade."
Until the user runs the above program, the product will run in NAG mode.
•
After entering the license through the GUI, a message will be printed similar to the following:
You have entered an upgrade license key. Please run the program
<NMSROOT>/bin/validate_upgrade.exe to validate the upgrade.
Until the user runs the above program, the product will run in NAG mode.
License CLI
Note
The following programs are provided to support the installation of licenses:
