Managing InterSystems IRIS Licensing
This topic contains an overview of the InterSystems IRIS® license system.
InterSystems Terms and Conditions govern how you may use the licensed InterSystems IRIS software. Occasionally, the implementation may be more lenient. Verify that any license-related code you write conforms to these terms and conditions.
Configuring InterSystems IRIS Licensing
Each InterSystems IRIS instance maintains an independent local view of its license capacity and current use, and each instance requires access to a license key (except evaluation installations). You may install and activate a local license key file on each instance. Or, if you are managing multiple instances, you may configure a license server to manage key files stored in a central location, which it can then distribute to other instances. In this case, each instance must be configured with the LicenseID of the key file, so that it can retrieve a copy of the key at startup.
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 InterSystems IRIS license servers to allocate the InterSystems IRIS 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 an InterSystems IRIS 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 an InterSystems IRIS process; it is unaffected if an InterSystems IRIS instance shuts down. One license server can handle multiple instances. Therefore, you need at most one per host regardless of how many InterSystems IRIS instances run on a host. However, each InterSystems IRIS instance must have a local copy of the authorizing license key file installed.
If you run InterSystems IRIS 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. 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 an InterSystems IRIS 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 iris.key file and all instances authorized by the same key use the same license servers. However license units are not summed across license keys. InterSystems IRIS instances using different license keys do not share license units, and users logged in to two instances using different license keys consume a separate license unit from each key.
Configuring License Servers
You can add or delete license servers from the License Servers page (System Administration > Licensing > License Servers) in the Management Portal. The page 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.
You can also determine which license server is active using the $System.License.ShowServer() method.
Click on the name of a listed license server to update its information, or click Delete to remove it. To add a new license server:
Click Create License Server to configure a license server. The Create New License Server box appears on the right edge of the screen.
Enter a name for the license server in the Name box. The license server name identifies the license server in the configuration and must be unique to a configuration.
Enter the IP address to host the license server in the Hostname/IP Address box. You can enter the IP address in dotted decimal format (18.104.22.168) 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).
Enter the port number used by the license server in the Port box. The license server port number must be a number between 1024 and 65535; InterSystems IRIS uses a default port number of 4002. Redundant license servers running on different hosts do not need to use unique port numbers, but must use port numbers that are not already in use at that IP address.
If a remote license server is protected by a firewall, the license server port must be open for UDP traffic.
(Optional) Enter the central directory where license keys are stored in the KeyDirectory box. For more information, see Loading Keys to the License Server.
Click Save to create the license server.
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.
Loading Keys to the License Server
In addition to managing the capacity of shared licenses, the license server may also distribute keys stored in a central directory to InterSystems IRIS instances.
A KeyDirectory property is defined as part of Config.LicenseServersOpens in a new tab. If this is filled in, the instance which starts the License Server reads any valid *.key files found there at startup and sends them to the License Server. Each key file must have a unique LicenseID property. The instance logs a count of files successfully loaded and any errors. You may manually reload key files from the directory to update any licenses by calling ReloadKeys^%SYS.LICENSE from the %SYS namespace.
Loading a new key with the same LicenseID as an existing key in the License Server key tables marks the existing key as replaced. Requests from instances for that LicenseID receive the most recently loaded key. You can use the existing $System.License.DumpKeys() method to view the current state of keys in the License Server.
Activating a License Key
InterSystems IRIS uses license keys to ensure proper operation of its registered sites, to define capacity available and to control access to InterSystems IRIS features. (License keys are not required for evaluation installations.) A license key is provided in the form of a license key file, typically named iris.key.
After installing InterSystems IRIS, 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 install-dir/mgr directory as iris.key, if it is not named that already.
You can also select a license key during Windows installation (see Installing InterSystems IRIS on Microsoft Windows ). When you do this, the license is automatically activated and the license key is copied to the instance’s install-dir/mgr directory as iris.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. 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 is 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 install-dir/mgr directory as iris.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 enables fewer features than the current license.
Instances can be configured to request a license key from the license server by using the LicenseID property of Config.StartupOpens in a new tab. At instance startup, if there is no iris.key file present and the LicenseID has been defined, then the instance requests and activates the license key from the license server.
The same LicenseID must be in the license key file, as well as defined on the instance that needs to download a license
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 shared 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 messages 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 InterSystems IRIS instance must be restarted to fully activate the new license key. This situation is rarely encountered, since each page represents at least 227 licenses.
Updating a License Key
To update a license key, replace the key file in the KeyDirectory and run ReloadKeys^%SYS.LICENSE. The License Monitor on each instance (^LMFMON) checks every 30 minutes to see if there is a different key for the configured LicenseID, and if so, tries to perform an upgrade.
While most upgrades succeed on a live instance, some conditions could require an instance be restarted. The License Monitor logs an error in this case, and does not try to upgrade the key again until the next day (to avoid logging repeated errors). An instance restart loads the new key at startup.
If only one user can log in after entering your license and restarting InterSystems IRIS, use the Management Portal to investigate. The License Usage page (System Operation > License Usage) shows how many processes are running when you select Usage 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 messages log and System Monitor log, which can be viewed in the Portal on the Messages Log page (System Operation > System Logs > Messages Log) and System Monitor Log page (System Operation > System Logs > System Monitor Log), respectively (see Monitoring Log Files). System Monitor writes license expiration warnings and alerts to these logs, while Health Monitor writes license acquisition alerts and warnings. When the license limit is exceeded, alerts are written to the messages log by the licensing module. In Application Monitor, you can configure license metric-based alerts to send email notifications or call notification methods. See Using System Monitor for more information.
When your license is nearing its expiration date, you will get warnings in the messages log. Your license is valid until the end of the day it expires on. For example, if your license has an expiration date of November 30, 2022, it will be valid until the end of November 30, 2022, but it will no longer work on December 1, 2022.
$System.License.Help displays a list of methods you can use to troubleshoot license problems:
This document describes many of these methods.
Administrator Terminal Session
Several problem can prevent you from obtaining a Terminal session. This can happen when InterSystems IRIS fails to start properly and enters single user mode, or simply when there are no licenses available. In these cases you may need to create an administrator terminal session, which uses a special license to allow you to resolve the problem.
The command to open an administrator session differs for Windows and for UNIX®, Linux, and macOS.
Administrator Session on Windows
Using the command prompt, navigate to install-dir\bin. Then, execute the following command as an administrator:
irisdb -s<install-dir>\mgr -B
This runs the InterSystems IRIS executable from the InterSystems IRIS installation bin directory (install-dir\bin), indicates the pathname of install-dir\mgr (using the -s argument), and inhibits all logins except one emergency login ( using the -B argument).
As an example, with an instance named MyIRIS located in the default directory, the command would look like:
c:\InterSystems\MyIRIS\bin>irisdb -sc:\InterSystems\MyIRIS\mgr -B
Administrator Session on UNIX®, Linux, and macOS
Using the command prompt, navigate to the install-dir/bin directory. Then, execute the following command:
iris terminal <instance-name> -B
As an example, with an instance named MyIRIS installed in the default directory, the command would look like:
User:/InterSystems/MyIRIS/bin$ iris terminal MyIRIS -B
Upgrading a License from the Operating System Command Line
The %SYSTEM.License.Upgrade()Opens in a new tab 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:
iris terminal <instancename> -U %SYS '##Class(%SYSTEM.License).Upgrade()'
For more information on the iris command, see Connecting to an InterSystems IRIS Instance.
Determining License Capacity and Usage
How does one know how many licenses have been used, and by whom? The %SYSTEM.LicenseOpens in a new tab class provides an interface to the InterSystems IRIS license application programming interface (API) and presents a number of methods and related queries that you can use to query license capacity and current use.
You can run a number of licensing queries using the RunQuery method of the %Library.%ResultSet class. For example:
You can view the output of these queries from the License Usage page of the Management Portal (System Operation > License Usage), as detailed in the following table:
|Link on License Usage Page
||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
||AllKeyConnectionList() — returns current distributed license usage sorted by users. (This is disabled when no license server is connected.)
You can also use the following class methods from the %SYSTEM.LicenseOpens in a new tab class 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 Web Gateway connections that can be made. From the Management Portal in the Web Gateway Management section:
Navigate to Server Access.
Select State-less Parameters.
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 slows 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 = 22.214.171.124, Connections = 1, CSP Count = 0, Time active = 49
$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 InterSystems IRIS instances currently supported by the license server. The Local license use section presents a view of license use for the single InterSystems IRIS 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 InterSystems IRIS 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 InterSystems IRIS 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 web 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 InterSystems IRIS 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 InterSystems IRIS 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, InterSystems IRIS 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.
Applications that identify their users by name eliminate problems associated with using a default user ID based on client IP address, web session ID, or other connection-derived user ID.
For example, when firewall or terminal server software is used, InterSystems IRIS cannot differentiate among connecting users, so it falls back on the maximum-connection transition rule. Using mixed connections 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 InterSystems IRIS 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, InterSystems IRIS 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 instance 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 ObjectScript commands, and then every 1000 ObjectScript 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 only 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.LicenseOpens in a new tab class. By default, InterSystems IRIS uses the client IP address to identify a user to the license tracking subsystem. If you installed InterSystems IRIS 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 InterSystems IRIS 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",!
The following example enables, then disables username licensing:
See the $USERNAME special variable entry in the 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.SessionOpens in a new tab equivalent method, %CSP.Session.Login, to identify a user for licensing purposes. If they do not, the web 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. In this case, you can use the %CSP.SessionOpens in a new tab method, %CSP.Session.Login(username, password) to perform an explicit license login for the session.
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 Instance Authentications) 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.
InterSystems IRIS 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 page (System Operation > Task Manager > New Task) (see Using the Task Manager) consumes a license unit, with the license user ID based on the InterSystems IRIS 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 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 the InterSystems licensing capabilities for their own licensing purposes. InterSystems IRIS manages customer application licenses just as it does its own application licenses, maintaining usage counts and acquiring and returning user licenses as needed. Application licenses consumed by a process or a web session are automatically released along with the InterSystems IRIS license consumed by the process or session when a process exits, halts or is deleted from the process table, or when a web 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 InterSystems IRIS 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 an InterSystems IRIS instance at application run time using the $SYSTEM.License.LoadAppLicenseFile method, which is documented in the %SYSTEM.LicenseOpens in a new tab class reference (see Application Licensing API). An application license loaded in this manner is not associated with the active InterSystems IRIS license, but is tracked independently by the InterSystems IRIS 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.LoadAppLicenseFileOpens in a new tab 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.
Extended Lab Reports=Enabled
An application license is not protected from tampering by InterSystems IRIS, 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.