T41.3: Manages Licenses

License Key Overview

InterSystems IRIS uses license keys to ensure proper operation of registered sites, define available capacity, and control access to features. License keys are not required for evaluation installations, but all production instances must have valid license keys. The license key is provided in a file typically named iris.key, which must be activated for the instance to operate within licensed parameters.

Activation via Management Portal

To activate a license key through the Management Portal: 1. Navigate to System Administration > Licensing > License Key 2. View current active license information (customer name, capacity, expiration date, enabled features) 3. If no license is activated, "License missing or unreadable" appears as the Customer Name 4. Click "Activate License Key" and browse to the license key file 5. Review displayed information to verify capacity and expiration date 6. If valid, both current and new license information displays side by side for comparison 7. Click "Activate" to complete the process

The system copies the license key to install-dir/mgr as iris.key, overwriting any previous license.

Restart Requirements

Most license upgrades do not require restart. However, restart is required when:

• Changing from Power Unit to any other license type
• New license requires at least 1000 64KB pages more gmheap space than the existing key (representing at least 227 licenses)

Windows Installation

On Windows, administrators can select a license key during installation, which automatically activates it without requiring manual activation.

License Servers

License servers provide centralized management for multiserver keys shared among multiple instances:

• A license server can run on any computer hosting an IRIS instance
• Coordinates license allocation when more than one instance shares a license
• One license server can handle multiple instances (at most one per host needed)
• Configure through License Servers page at System Administration > Licensing > License Servers
• Specify name, hostname/IP address (stable, consistent address required), port (default 4002, must be 1024-65535)
• After adding or removing license servers, restart the IRIS instance
• If multiple instances share a license, delete the default LOCAL license server (127.0.0.1) on each instance

Updating License Keys

• Replace the key file in the KeyDirectory and run ReloadKeys^%SYS.LICENSE
• The License Monitor (^LMFMON) checks every 30 minutes for different keys matching the configured LicenseID
• If restart is needed, the License Monitor logs an error and waits until the next day to retry

Common Symptoms

The most common symptom of license problems is that only one user can log in after entering a license and restarting InterSystems IRIS. This typically indicates either an invalid license configuration or license capacity exhaustion.

Using the License Usage Page

The License Usage page (System Operation > License Usage) is the primary tool for diagnosing license consumption issues:

• Select "Usage by Process" to see how many processes are running and consuming license units
• View operating system process identifier (PID), namespace, routine name, process state, and device for each active process
• Identify which processes are consuming capacity and take appropriate action

Using the License Key Page

The License Key page (System Administration > Licensing > License Key) displays:

• Customer name (or "License missing or unreadable" if invalid)
• License capacity in various units
• Expiration date
• Enabled features

Verify that license capacity matches requirements, expiration date is current, and necessary features are enabled.

Command-Line Upgrade When Locked Out

If all license units are consumed, preventing Terminal access to activate a new license: ``` iris terminal -U %SYS '##Class(%SYSTEM.License).Upgrade()' ``` This activates a new license key that has been copied to the install-dir\mgr directory.

Programmatic Diagnostics

The %SYSTEM.License class provides numerous methods and queries:

• $System.License.CKEY(): Displays current license key information (equivalent to ^CKEY program)
• $System.License.ShowSummary: Displays license usage summary
• $System.License.DumpLocalPID: Shows license use by operating system process identifier
• $System.License.ShowCounts: Summarizes license use tracked in shared memory
• $System.License.ShowServer(): Determines which license server is active

Available Queries

Run queries using `##class(%ResultSet).RunQuery("%SYSTEM.License","query-name")`:

• Summary(): Usage summary
• ProcessList(): Use by PID
• UserList(): Use by User ID
• AllKeyConnectionList(): Distributed license usage (requires active license server connection)

Network Considerations for License Servers

• Each license monitor queries the license server via TCP
• Firewall rules must permit this traffic
• If a remote license server is protected by a firewall, the license server port must be open for UDP traffic
• License server IP addresses should be stable; if the IP address changes, the License Monitor enters restart mode

Multiserver Key Considerations

When instances share multiserver keys:

• Ensure all instances are configured to use the same license server(s)
• Each instance needs its own copy of the proper iris.key file
• All instances authorized by the same key must use the same license servers
• License units are not summed across different license keys
• Users logged into two instances with different keys consume a separate license unit from each key