Managing Caché Licensing
This chapter contains an overview of the Caché license system; it covers the following topics:
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.
Configuring License Servers
Configure the license servers using the Management Portal:
Navigate to the License Servers page (System Administration > Licensing > License Servers).
This displays a list of license servers configured for this instance. When there are multiple license servers configured for this instance, the row of the active license server is shaded. From this page you can edit or delete an existing server definition or add a new server.Note:
You can also determine which license server is active using the $System.License.ShowServer() method.
Click Create License Server to configure a license server.
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.
The license server name identifies the license server in the configuration and must be unique to a configuration.
You can enter the IP address in dotted decimal format (22.214.171.124) 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.
Click the name of a listed license server to update the information described in the previous step.
Click Delete to remove a license server from the configuration.
After adding or deleting a license server, you must restart the InterSystems IRIS instance.
If separate instances all configure the same license server address and port, they all use the same license server; when this is the case, you should delete the default LOCAL license server (127.0.0.1) on each instance. 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.
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:
Navigate to the License Key page (System Administration > Licensing > License Key). 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.
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.
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 Advanced Memory Settings page (System Administration > Configuration > Advanced Memory Settings).
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.
If, after entering your license and restarting Caché, only one user can log in, use the Management Portal to investigate. The License Usage page (System Operation > License Usage) shows how many processes are running when you select By Process. You can also use the portal to display license information from the License Key page (System Administration > Licensing > License Key), 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 page (System Operation > System Logs > Console Log) and the System Monitor Log page (System Operation > System Logs > System Monitor Log). See the 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:
This document describes many of these methods. If your license problem prevents you from obtaining a terminal session, open a command line window, change to install-dir/bin, and run the following command as administrator to get one additional Terminal session 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, as follows:
csession <instancename> -U %SYS '##Class(%SYSTEM.License).Upgrade()'
For more information on the csession command, see Connecting to a Caché Instance in the “Using Multiple Instances of Caché” chapter of this guide.
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 License Usage page (System Operation > License Usage), as detailed in the following table:
|Link on 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:
$System.License.ShowCounts summarizes license use tracked in shared memory on the local system:
$System.License.ShowServer displays the active license server address and port:
If you have developed REST based applications, your licenses will be consumed with use. To prevent this from happening, configure the number of CSP Gateway connections that can be made. From the SMP in the CSP Gateway Management section:
Navigate to Server Access.
Select State-less Paramaters.
Set the Maximum to a number 2 or 3 less than the license to allow for server-side logins.
Depending on the server side needs of the application you will need to adjust this.
By doing this when all the available connections are busy, new requests will queue up rather than being rejected. You will not see a rejection due to license counts being exceeded. As volume grows, the response time for the client will slow down. That would be the indication that you need to buy more licenses.
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:
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 = 126.96.36.199, 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:
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:
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:
$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:
$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:
$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:
$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:
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.
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:
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®/Linux systems 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 its first 4000 Caché commands, and then every 1000 Caché commands after that.
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.
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:
$SYSTEM.License.UserNameLicensing(1) — enables $USERNAME based licensing and returns the previous state.
$SYSTEM.License.UserNameLicensing(0) — disables $USERNAME based licensing and returns the previous state.
$SYSTEM.License.UserNameLicensing() — returns the current state. May return an error if called with an argument for license types that use special login rules.
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:
CSP connections are a special case for logins. InterSystems strongly recommends that CSP applications use the %CSP.Session equivalent method, %CSP.Session.Login, to identify a user for licensing purposes. If they do not, the CSP session ID is used as the license user ID. Each session consumes a license unit, which in many cases is unsuitable. For example, a user can have several browser windows open concurrently. Alternatively, a user can connect via several pathways (CSP, a terminal window, and a Caché Direct connection from a Visual Basic client). In this case, you can use the %CSP.Session method, %CSP.Session.Login(username, password) to perform an explicit license login for the session.Note:
When a CSP session ends (from a logout or timeout) and the user has visited only one page, CSP does not immediately release the license. Instead, CSP reserves the license for that user for a grace period of up to 10 minutes.
Anonymous SOAP requests (that is, SOAP requests that do not require Caché logins) consume a license unit for minimum of 10 seconds; however, any SOAP request that identifies the user requires a license because it is considered a “user request.” Information about implementing a SOAP session is available in SOAP Session Management in Creating Web Services and Web Clients in Caché.
Caché does not distinguish background processes and count them differently. If a user process starts another process, that child process counts as one more against the user’s overall maximum limit of processes.
Each task created using the New Task option on the Task Manager page (System > Task Manager) consumes a license unit, with the license user ID based on the Caché username specified by the Run task as this user selector and the loopback IP address, 127.0.0.1, which is converted to the host IP address. This ensures that tasks running as a given user on different hosts are counted together against the maximum limit of processes for that user discussed in Identifying Users.
Processes started by the user startup routines (^%ZSTART, or the older ^ZSTU, and ^ZMIRROR) are another special case. The process running the routine has no parent process. Therefore, a login is performed for the user ID, User Startup, before the routine is called. Processes started by the Job command from the routine have this user ID. If you prefer, you can call $System.License.Login(UserId) from the routine to change the user ID. This procedure means that the routine can start as many as one less than maxconn background processes and only consume one license. If, according to the license terms and conditions, these processes should have a separate license (for example if they drive a piece of laboratory equipment that requires a separate license), you are required to call $System.License.Login(UserId) to obtain a license for an appropriate user ID.
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:
Loads an application license from a file.
Returns the contents of a currently loaded application license as a string of keyword=value pairs.
Retrieves the maximum number of consumed license units associated with an application license keyword since the license was loaded
Returns the names of applications currently licensed by InterSystems, InterSystems application partners, or both.
Indicates whether an application or feature is licensed.
Consumes a license unit for an application and feature. The license user ID of the current process (or in the case of CSP, the session license ID) is the user identifier associated with the application license consumed.
Releases a license unit for an application license and feature, including the license resource associated with the license user ID of the current process, or the session license ID in the case of CSP.
Indicates whether the number of instances using a currently loaded application license exceeds the limit specified in the key.
Retrieves the value associated with an application license feature keyword.
Retrieves the minimum number of free license units associated with an application license feature keyword, where the value associated with the keyword is numeric.
Retrieves the number of free license units associated with an application license feature keyword, where the value associated with the keyword is numeric.
Retrieves a $List of application license types taken for the Process PID or "" for none
Returns license and application license use by user ID.