The license management system has been reconstructed in Caché 5. It reflects
changes to the way Caché is licensed. This new licensing system meets a primary
objective of making license management more robust than earlier implementations of
Caché.
Important:
InterSystems Terms and Conditions govern how you may
use the licensed Caché software. Occasionally, the implementation may be less
lenient. Verify that any license-related code you write conforms to these terms and
conditions.
This section covers the following topics:
The Caché license management system attempts to identify distinct users
and to charge 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 a maximum limit of processes per user. The
$System.License.MaxConnections() method
returns the maximum value (
maxconn) for the current implementation.
Set maxconn=$System.License.MaxConnections()
Write "Maximum connections = ",maxconn
If the number of processes exceeds this maximum, a transition occurs and Caché
begins charging one license unit per process for that user ID. The system presumes
that if more than
maxconn connections are associated with a user
ID, multiple users are accessing Caché through an intermediary, (for example,
a firewall system) so additional license units are required. Therefore, when the (
maxconn +
1)
process starts, the number of license units charged to that user ID changes from one
to (
maxconn +
1). Processes started by the
Job command
are charged against the process limit of the user ID invoking the
Job command.
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.
There are two modes of license login: automatic and explicit. Automatic login
remains the default in Caché 5. 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. When connections originate from a terminal
server using the LAT protocol, the terminal server name and port name (obtained from
$ZIO) are combined to form a user ID. Hence, a user with multiple
sessions from a terminal server port is charged a single license unit. 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 explicit login is selected, no automatic detection of a user ID is attempted.
The application must explicitly call the
$System.License.Login(UserIdentifier) method
to supply the license user ID and acquire a license.
Explicit login is enabled by calling the
$System.License.DeferUserIdentification([0
or 1]) function. This call can be made from 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 login is deferred, the customer must call the license login method immediately.
A process that has not performed a license login pauses for 15 seconds after each
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.
CSP connections are a special case for logins. We strongly recommend 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 class method,
%CSP.Session.Login(UserId,Password,[0
or 1]) to perform an explicit license login for the session.
Processes started by the user start 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) from
^%ZSTART 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), then you are required to call
$System.License.Login(UserId) to
obtain a license for an appropriate user ID.
Finally, it is important to understand that Caché 5 no longer tries to
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.
Configuring Caché 5 Licensing
The major difference between Caché 5 and earlier versions of Caché
is that each configuration maintains an independent local view of its license capacity
and current use. Each configuration requires access to the key; therefore a
cache.key file
must be installed on every configuration. Multiserver keys can be shared among cooperating
configurations, either on the same machine or on different machines. Please note that
Enterprise keys are not automatically sharable as they were in earlier versions. Sharing
is permitted only with multiserver keys.
Sharing multiserver keys requires coordination among configurations using the
key. Caché 5 introduces a license manager that replaces the license server
in version 4.1 and earlier versions of Caché. When multiserver keys are shared,
a license manager must be configured. The license manager coordinates the views of
license use maintained locally in every configuration. One license manager can handle
multiple configurations. The license manager is not a Caché process; it is
unaffected if a Caché configuration shuts down. This avoids past problems when
the license server became unreachable if a configuration shut down or paused during
backup. The license manager communicates with configurations via UDP messages on a
configurable port. The default port is
4001.
License managers are defined in the
Caché Configuration
Manager in the
License section of the
Advanced tab.
You can configure redundant license managers. This is much less critical than with
previous Caché versions for two reasons. First, the configuration can continue
running with users logging in and out in the absence of the license manager. Second,
the license manager continues running after configuration shutdown when it is supporting
more than one configuration. When configuring license managers, decide which server
or servers you want to host the license manager. You can configure it to run on as
many hosts as you want, but more than three is excessive. Since the license manager
is started by a running configuration, it should be configured to run on systems where
you expect a Caché configuration to be running consistently. If you configure
redundant license managers there is no need to use different port numbers as was necessary
with license servers.
A license key can be upgraded by placing it in the appropriate directory on
the Caché server, or by using the license wizard in the
Caché
Configuration Manager. When the wizard enters and saves the key, the
working version of the key is automatically updated and activated. If upgrading manually,
invoke the
$System.License.Upgrade method from the
%SYS namespace.
In general there is no need to restart the configuration.
There are constraints when upgrading a license type. 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. Most license upgrades are expected to just increase
the number of license units or change from single-server to multiserver licenses.
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. There is
also a limit to the amount of
gmheap space (10 pages) that a license
upgrade consumes. This limit permits a maximum of slightly more than 7,000 additional
license units to be activated. This is the incremental count, not the total, so if
you have a 30,000 Concurrent User key, you can upgrade it to slightly more than 37,000
license units without restarting the configuration. If you upgrade your license by
purchasing more than 7,000 additional license units, approximately 7,000 additional
license units are activated, but a restart is necessary to activate the rest.
Determining License Capacity
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 large number of methods that can be used to query license capacity
and current use. You can run these class methods using the special
$System object;
they are described in the
Caché Class Reference. Invoke
the following class methods to display information or dump the license database to
a file:
Do $System.License.CKEY()
Do $System.License.ShowCounts()
Do $System.License.ShowManager()
Methods to Show Local License Information
The subroutines listed below dump the contents of license tables contained locally
in configuration-shared memory. In general, they identify the client:
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
Do $System.License.DumpLocalInUse()
An example of the contents of the
inuse.dmp file:
License Capacity = 5, Current use = 2, Units Remaining = 3
Do $System.License.DumpLocalPID()
An example of the contents of the
piduse.dmp file:
License Capacity = 5, Current use = 2, Units Remaining = 3
Methods to Show License Manager Information
The following subroutines dump the contents of license tables maintained by
the license manager. The output files are in the indicated directory on the host where
the active license manager is running.
$System.License.ShowSummary displays a summary of license
information at the license manager. The
Distributed license use section
presents a collective view of license use for all Caché configurations currently
supported by the license manager. The
Local license use section
presents a view of license use for the single Caché configuration in which
the program is run:
Do $System.License.ShowSummary()
Do $System.License.DumpServer()
Do $System.License.DumpServers()
Do $System.License.DumpKey()
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 manager methods; the license
manager is only updated periodically, while the local data is real time.