Caché System Administration Guide
Managing Caché Licensing
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

This chapter contains an overview of the Caché license system; it covers the following topics:

Important:
Licenses from versions prior to Caché 5.1 do not work with this version of Caché. Please contact the InterSystems Worldwide Response Center (WRC) for an appropriate key if you are upgrading from an older version.
InterSystems Terms and Conditions govern how you may use the licensed Caché software. Occasionally, the implementation may be more lenient. Verify that any license-related code you write conforms to these terms and conditions.
Configuring Caché Licensing
Each Caché instance maintains an independent local view of its license capacity and current use. Each instance requires access to the key; therefore you must install and activate a license key file (typically named cache.key) on every instance, except evaluation installations.
Multiserver licenses can be shared among cooperating instances, either on the same machine or on different machines. Sharing is permitted only with multiserver keys. To use your multiserver licenses, you must configure one or more Caché license servers to allocate the Caché license units authorized by the key. All instances sharing a key must be configured to use the same license server or set of license servers. License servers can run on any computer where you run a Caché instance. A monitor process sends update messages to the license server, which coordinates license allocation when more than one instance shares a license.
The license server coordinates the views of license use maintained locally in every instance. The license server is not a Caché process; it is unaffected if a Caché instance shuts down. One license server can handle multiple instances. Therefore, you need at most one per host regardless of how many Caché instances run on a host. However, each Caché instance must have a local copy of the authorizing license key file installed.
If you run Caché servers on multiple hosts, you can configure more than one license server to provide redundancy. The license software selects one of the license servers to be the active server. The other servers are available to take over should the active server fail. This is much less critical than with previous Caché releases because the instance can continue running with users logging in and out in the absence of the license server, and the license server continues running after shutdown when it is supporting more than one instance. When configuring license servers, decide which server or servers you want to host the license server. You can configure it to run on as many hosts as you want, but more than three is excessive. Since the license server is started by a running instance, it should be configured to run on systems where you expect a Caché instance to be running consistently.
Multiple instances with different license keys and running on different platforms can use the same license server to coordinate licensing as long as each instance has its own copy of the proper cache.key file and all instances authorized by the same key use the same license servers. However license units are not summed across license keys. Cache instances using different license keys do not share license units, and users logged into two instances using different license keys will consume a separate license unit from each key.
Configure License Servers
Configure the license servers using the Management Portal:
  1. Navigate to the [Home] > [Licensing] > [License Servers] page.
  2. This displays a list of license servers configured for this installation. From this page you can edit or delete an existing server definition or add a new server.
  3. Click Add to configure a license server.
  4. Enter a name for the license server in the Name box, the IP address of the host on which it runs in the Hostname/IP Address box, and the port number used by the license server in the Port box.
    Note:
    The name identifies the license server in the configuration and must be unique to a configuration.
    A license server is defined by the IP address of the host on which it runs and the port it uses to communicate. You can enter the IP address in dotted decimal format (192.29.233.19) or in alphabetic format (mycomputer.myorg.com). If IPv6 is enabled, you can enter a colon separated format IPv6 address (2001:fecd:ba23:cd1f:dcb1:1010:9234:4085). The license server port number must be a number between 1024 and 65535; InterSystems uses a default port number of 4001. The port numbers of redundant license servers running on different hosts do not need to be unique, but must be different from any port number used at that IP address.
  5. Click the name of a listed license server to update it the information described in the previous step.
  6. Click Delete to remove the license server from the configuration.
The row of the active license server is shaded when there are more than one license servers configured for this instance.
You can also view which license server is active using the $System.License.ShowServer method:
 Do $System.License.ShowServer()
 
Note:
If separate instances all configure the same license server address and port, they all use the same license server. If the same key is loaded on each instance, they share the key. If different keys are loaded on each instance, the license server serves each set of instances using each key separately.
Activating a License Key
Caché uses license keys to ensure proper operation of its registered sites, to define capacity available and to control access to Caché features. (License keys are not required for evaluation installations.) A license key is provided in the form of a license key file, typically named cache.key.
After installing Caché, use the following procedure to activate your license key. You can always use the same procedure to activate a new license key (that is, upgrade the key) for any installed instance. You can activate a license key placed in any location accessible to the management portal; as part of activation, the license key is copied to the instance’s manager directory (install-dir/mgr) as cache.key, if it is not named that already.
Note:
You can also select a license key during Windows installation (see the chapter Installing Caché on Microsoft Windows in the Caché Installation Guide). When you do this, the license is automatically activated and the license key is copied to the instance’s manager directory as cache.key; the activation procedure described here is not required.
This section also discusses license troubleshooting and upgrading a license from the operating system command line when all license units are in use.
To activate a license key, use the following procedure:
  1. Navigate to the [Home] > [Licensing] > [License Key] page. Information about the current active license key is displayed. If no license has yet been activated, this is indicated, for example by the notation Customer Name: License missing or unreadable. This page includes a Print button to let you easily print the displayed information.
  2. Click Activate License Key and browse for the license key file you want to activate (typically but not necessarily named cache.key). When you select a file, information about it is displayed so you can verify that you have the right license key before activating it; for example, that it provides the desired capacity, and has the right expiration date. If the key is not valid, this is indicated in an error message. If a license is currently active, information about the current and selected licenses is displayed side by side. If a restart of the instance after activation will be required for the license key to take effect, this is noted and the reason for it is provided. This dialog includes a Print button to let you easily print information about both the current active license and the new license key you have selected.
  3. Click Activate to activate the new license key; it is copied to the instance’s manager directory as cache.key, overwriting the previous license key (if any). A confirmation dialog reminds you to restart the instance, if required, and warns you if the new license will enable fewer features than the current license if this is the case.
In general there is no need to restart the instance, but there are constraints when upgrading a license key. Automatic activation of the new key does not occur if you change license types from Power Unit to any other type; this should be a rare event.
Another constraint is the amount of memory the license upgrade consumes from the generic memory heap (gmheap) space. If gmheap space is not available, the number of license table entries cannot be expanded. If insufficient gmheap space is available for a license upgrade, a message is written to the console log. You can increase the size of the gmheap setting from the [Home] > [Configuration] > [Advanced Memory Settings] page of the Management Portal.
If the new license key consumes at least 1000 64 KB pages more gmheap space than the existing key, the Cache instance must be restarted to fully activate the new license key. However, since each page represents 227 licenses on a unicode system and more on an 8-bit system, this situation is rarely encountered.
License Troubleshooting
If, after entering your license and restarting Caché, only one user can log in, use the management portal to investigate. The [Home] > [License Usage] page shows how many processes are running when you select By Process. You can also use the portal to display license information from the [Home] > [Licensing] > [License Key] page, as described in Activating a License Key. If the key is not valid, the CustomerName field contains an explanation.
You can also check the license error messages in the console log and System Monitor log, which can be viewed in the portal on the [Home] > [System Logs] > [Console Log] page and [Home] > [System Logs] > [System Monitor Log] page, respectively (see Monitoring Log Files section of the “Monitoring Caché Using the Management Portal” chapter of the Caché Monitoring Guide). Caché System Monitor writes license expiration warnings and alerts to these logs, while Caché Health Monitor writes license acquisition alerts and warnings. When the license limit is exceeded, alerts are written to the console log by the licensing module. In Caché Application Monitor, you can configure license metric-based alerts to send email notifications or call notification methods. See the Using Caché System Monitor chapter of the Caché Monitoring Guide for more information about these monitoring tools.
$System.License.Help displays a list of methods you can use to troubleshoot license problems:
 Do $System.License.Help()
 
This document describes many of these methods. If your license problem prevents you from obtaining a terminal session, open a Command Prompt window run as Administrator, change to install-dir/bin, and run the following command to get one additional terminal session within the Command Prompt window for license troubleshooting purposes:
cache -s ..\Mgr -B
Upgrading a License from the Operating System Command Line
The %SYSTEM.License.Upgrade() method activates a new license key that has been copied to the installdir\mgr directory. If all license units are consumed by users, preventing you from opening a Terminal window, you can run this method from the command line to activate a new license key with a greater capacity. For example, on a Windows system you would use the following command line:
bin\cache -s mgr -U %SYS ##Class(%SYSTEM.License).Upgrade()
On a UNIX®/Linux system, the command would be as follows:
csession <instancename> -U %SYS '##Class(%SYSTEM.License).Upgrade()'
Determining License Capacity and Usage
How does one know how many licenses have been used, and by whom? The %SYSTEM.License class provides an interface to the Caché license application programming interface (API) and presents a number of methods and related queries that can be used to query license capacity and current use. You can run these class methods using the special $System object. See the %SYSTEM.License class entry in the InterSystems Class Reference for details.
You can also run the methods using the [Home] > [License Usage] page in the management portal, as detailed in the following table:
Link on [Home] > [License Usage] License Query
Summary Summary() — returns license usage summary as displayed by $System.License.ShowSummary.
Usage by Process ProcessList() — returns license use by the operating system process identifier (PID) as displayed by $System.License.DumpLocalPID.
Usage by User UserList() — returns license use by User ID.
Distributed License Usage Summary() — returns current distributed license usage sorted by users as displayed in the Distributed Licence Use section of $System.License.ShowSummary. (Link is disabled when no license server is connected.)
You can also use the following class methods to display information or dump the license database to a file:
$System.License.CKEY displays the key. This subroutine is called by the ^CKEY program which is retained for compatibility:
 Do $System.License.CKEY()
 
$System.License.ShowCounts summarizes license use tracked in shared memory on the local system:
 Do $System.License.ShowCounts()
 
$System.License.ShowServer displays the active license server address and port:
 Do $System.License.ShowServer()
 
The following sections describe several other methods that show license information:
Methods to Show Local License Information
The subroutines listed below dump the contents of license tables contained locally in instance shared memory. In general, they identify the client:
$System.License.DumpLocalAll dumps all local license table entries to the all.dmp file in the current directory:
 Do $System.License.DumpLocalAll()
 
An example of the contents of the all.dmp file:
License Capacity = 5, Current use = 2, Units Remaining = 3

   0)  User ID = 127.0.0.1, Connections = 2, CSP Count = 0, Time active = 90
   1)  User ID = 192.9.202.81, Connections = 1, CSP Count = 0, Time active = 49
   2)  free
   3)  free
   4)  free
$System.License.DumpLocalInUse dumps all local license table entries in use to the inuse.dmp file in the current directory:
 Do $System.License.DumpLocalInUse()
 
An example of the contents of the inuse.dmp file:
License Capacity = 5, Current use = 2, Units Remaining = 3
$System.License.DumpLocalPID dumps local license table use by process ID to the piduse.dmp file in the current directory:
 Do $System.License.DumpLocalPID()
 
An example of the contents of the piduse.dmp file:
PID     Process LID     Type    Con     MaxCon  CSPCon  LU      Active  Grace

592     System                  0       0       0       0       0       0
2816    System                  0       0       0       0       0       0
688     System                  0       0       0       0       0       0
Methods to Show License Server Information
The following subroutines dump the contents of license tables maintained by the license server. The output files are in the indicated directory on the host where the active license server is running.
$System.License.ShowSummary displays a summary of license information at the license server. The Distributed license use section presents a collective view of license use for all Caché instances currently supported by the license server. The Local license use section presents a view of license use for the single Caché instance in which the program is run:
 Do $System.License.ShowSummary()
 
$System.License.DumpServer dumps the license server database information relating to the server from which you run this routine to the file, dumpserver.txt, on the host running the license server:
 Do $System.License.DumpServer()
 
$System.License.DumpServers dumps the license server database information for all known servers to the file, dumpservers.txt, on the host running the license server:
 Do $System.License.DumpServers()
 
$System.License.DumpKey dumps the key used by this instance and instances that share it to the file, dumpkey.txt, on the host running the license server:
 Do $System.License.DumpKey()
 
$System.License.DumpKeys dumps all keys, showing the instances and clients using them to the file, dumpkeys.txt, on the host running the license server:
 Do $System.License.DumpKeys()
 
Note:
Be aware that the information displayed by the local license methods is more up-to-date than the information shown by the license server methods; the license server is only updated periodically, while the local data is real time.
It is possible to exceed the license limit temporarily because login is controlled locally, but the license server enforces the limit. Each instance permits or denies logins based on its local license table which is maintained in instance shared memory. Each instance sends periodic updates to the license server describing changes to the local license tables. If the combined license use of all instances exceeds the limit, the license server sends a negative acknowledgment to update messages from each instance.
This negative acknowledgment causes each instance to refuse new logins because no additional license units are available. A login is considered new when the license user ID of the Caché process attempting to start does not match the license user ID of any current process. This state persists until the combined use by all instances falls below the authorized limit, at which point the license server begins sending positive acknowledgments in response to instance updates. The individual instances then allow new logins.
Identifying Users
The Caché licensing system attempts to identify distinct users and to allocate one license unit per user. A user is identified by a license user ID, which can be an IP address, a username, a CSP session ID, or some other identifier depending on how the user connects.
Multiple processes started by or for a single user share a license unit up to the maximum number of processes per user. If the number of processes exceeds this maximum, a transition occurs and Caché begins allocating one license unit per process for that user ID. The system assumes that if the number of processes associated with a user ID exceeds the maximum, multiple users are accessing Caché through an intermediary (for example, a firewall system), so additional license units are required. (Processes started by the Job command are counted under the user ID invoking the command.)
Even if the number of processes under the user ID drops back under the maximum, Caché continues to allocate one license unit per process for that user ID. Only when all connections by the user ID are closed and there are no more processes under the user ID does license allocation reset to one unit for that user ID.
InterSystems expects that most applications are moving to identify their users by name, eliminating problems associated with using a default user ID based on client IP address, CSP session ID, or other connection-derived user ID.
For example, when firewall or terminal server software is used, Caché cannot differentiate among connecting users, so it falls back on the maximum-connection transition rule. Using mixed connections, such as CSP and Caché Direct, from the same client also makes it impossible to count users appropriately using automatic ID creation.
When the username serves as the license identifier, these problems disappear. The importance of accurate user identification is expected to grow as organizations implement new access and audit requirements. Using the user identity to control license compliance is a natural corollary to this trend.
This section covers the following topics:
License Logins
There are two modes of license login: automatic and explicit. Automatic login is the default. The licensing system attempts to identify the IP address of the client and uses it as the license user ID. This works well when clients connect directly to the server using IP. It does not work well if a firewall intervenes between the client and the server; all clients appear to have the same IP address. When a terminal server is used with the telnet protocol, automatic login cannot differentiate among users because Caché sees a single IP address for all terminal server ports. Since all connections originate from the same address, all connections have the same user ID. If users connect through a firewall or use the telnet transport from terminal servers, use explicit logins.
When IP is not used as the network transport, the IP address is not available for use as a license user ID. In these cases, the licensing system uses a variety of other sources as the license user ID. Batch processes started by the at daemon on UNIX® or from a batch queue on OpenVMS pose another special case. Such processes do not share a license unit because they are not associated with a user. For these processes, the process ID is used as the license identifier.
When you select explicit login, Caché does not attempt automatic user ID detection. The application must explicitly call the $System.License.Login(UserIdentifier) method to supply the license user ID and acquire a license.
Enable explicit login by calling the $System.License.DeferUserIdentification([0 or 1]) function. You can make this call from the SYSTEM entry point in the ^%ZSTART routine at system startup. If the argument value is 1, license acquisition is deferred at login, so an explicit login can be performed. If the argument value is 0, license acquisition is automatic at process startup.
When you defer login you must call the license login method immediately. A process that has not performed a license login pauses after every 1000 lines of Caché ObjectScript code.
Use an explicit login for any case that automatic login does not handle. It is important to remember that, even if automatic login is configured, it is always possible to call $System.License.Login(UserIdentifier) to use explicit user identification for licensing purposes.
Username Licensing
You can use the value of $USERNAME to identify users for licensing. This enables more accurate counting in situations where you cannot use the IP address to reliably identify distinct users.
You modify how you specify the license user ID using the $SYSTEM.License.UserNameLicensing() method of the %SYSTEM.License class. By default, Caché uses the client IP address to identify a user to the license tracking subsystem. If you installed Caché with higher than Minimal initial security settings, each process has a user ID ($USERNAME). You can call the $SYSTEM.License.UserNameLicensing() system method to make the Caché license subsystem use $USERNAME as the license user identifier.
The $SYSTEM.License.UserNameLicensing() method modifies the system state. You can also call it from SYSTEM^%ZSTART to enable username licensing at instance startup. The method has the following functions:
For example, the following displays whether username licensing is currently enabled or disabled:
 Write " Username Licensing",!
 Write " 1-enabled, 0-disabled",!
 Write $SYSTEM.License.UserNameLicensing(),!
 
The following example enables, then disables username licensing:
 Set RC=$SYSTEM.License.UserNameLicensing(1)
 Write RC,!
 Set RC=$SYSTEM.License.UserNameLicensing(0)
 Write RC
See the $USERNAME special variable entry in the Caché ObjectScript Reference for more information.
License Login Special Considerations
Bear in mind the following special considerations concerning license logins:
Application Licensing
Application licensing enables InterSystems application partners to take advantage of Caché’s licensing capabilities for their own licensing purposes. Caché manages customer application licenses just as it does Caché/Ensemble and InterSystems application licenses, maintaining usage counts and acquiring and returning user licenses as needed. Application licenses consumed by a process or a CSP session are automatically released along with the Caché license consumed by the process or session when a process exits, halts or is deleted from the process table, or when a CSP session times out or is deleted.
An application license is simply a file in standard .ini format, or a section of such a file, containing a section header identifying the application and some number of keyword=value pairs, unique within the license, representing the features licensed. Any correctly formatted application license can be loaded into Caché by an application at run time.
The application licensing API includes methods and queries that enable applications to consume and return licenses on behalf of a user and programs to obtain information about application and feature licensing, including the number of licenses in use and still available.
Loading an Application License
Any application license can be loaded and activated by a Caché instance at application run time using the $SYSTEM.License.LoadAppLicenseFile method, which is documented in the %SYSTEM.License class reference (see Application Licensing API). An application license loaded in this manner is not associated with the active Caché license, but is tracked independently by the Caché instance.
Each application license is contained in a section beginning with [AppName]; the application name (AppName) cannot contain a period (.). The remainder of the license consists of a sequence of non-repeating keyword=value pairs representing the features licensed. See the $SYSTEM.License.LoadAppLicenseFile method documentation for more information about the required format.
In the following sample application license, the customer uses keyword=value pairs to limit the number of licensed users for several application features and enable the Extended Lab Reports feature for all users.
[BestLabApplication]
Lab Users=50
Lab Administrators=2
Lab Devices=5
Extended Lab Reports=Enabled
An application license is not protected from tampering by Caché, but it can be protected by custom application code. For example, a checksum can be embedded in the keyword section and validated by the application prior to activation.
Application Licensing API
The %SYSTEM.License class provides the following methods for managing application licenses: