Caché System Administration Guide
Managing Caché Licensing
This chapter contains an overview of the Caché license system; it covers the following topics:
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:
Navigate to the [Home] > [Licensing] > [License Servers]
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.
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
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 (188.8.131.52
) 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
; 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 it the information described in the previous step.
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.
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.
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.
To activate a license key, use the following procedure:
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
button to let you easily print the displayed information.
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
button to let you easily print information about both the current active license and the new license key you have selected.
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.
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
. 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.
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:
Upgrading a License from the Operating System Command Line
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
You can also run the methods using the [Home] > [License Usage]
page in the management portal, as detailed in the following table:
You can also use the following class methods to display information or dump the license database to a file:
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:
An example of the contents of the all.dmp
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 = 184.108.40.206, Connections = 1, CSP Count = 0, Time active = 49
An example of the contents of the inuse.dmp
License Capacity = 5, Current use = 2, Units Remaining = 3
An example of the contents of the piduse.dmp
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.
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:
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® 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.
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.
For example, the following displays whether username licensing is currently enabled or disabled:
Write " Username Licensing",!
Write " 1-enabled, 0-disabled",!
The following example enables, then disables username licensing:
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.
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
option on the [Home] > [Task Manager]
page in the Management Portal (see Using the Task Manager
in the Managing Caché
chapter of this guide) 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 routine (^%ZSTART
or the older ^ZSTU
) are another special case. The process running ^%ZSTART
has no parent process. Therefore, a login is performed for the user ID, User Startup
, before ^%ZSTART
is called. Processes started by the Job
command from ^%ZSTART
have this user ID. If you prefer, call $System.License.Login(UserId)
to change the user ID. This procedure means that ^%ZSTART
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
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.
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