Skip to content

License requirements and management

This page explains the license that KX Sensors v3 requires, which feature flags it needs, where to install it, how to replace it before it expires, and what happens if it expires.

KX Sensors v3 reads a single KX license file at startup. This replaces the two licenses that v2 required, a kdb+ license and a separate Delta Control (Delta Platform) license. The license also sets limits on your deployment, such as the number of cores, and enables individual features through feature flags.

If you're migrating from KX Sensors v2, your license is likely a k4.lic without additional flags (see License formats). It continues to work with KX Sensors v3 as long as you don't require multi-node with Reliable Transport (RT), Dashboards, REST, or PyKX.

Prerequisites

To manage your license, you need:

  • Access to each host in your deployment, with permission to write to $KXS_ROOT/lic.
  • A KX license file (k4.lic or kc.lic). To request one, contact KX.

Required feature flags

Your license must include the feature flag for each optional feature you use.

Feature Short flag Long flag Required when
RT rt insights.app.rt You run a multi-node deployment with RT. Not required for a single node.
KX Dashboards dsh You use KX Dashboards (v3.3 and later).
REST rs insights.lib.restserver You call APIs over REST.
PyKX py insights.lib.pykx You use PyKX.

Check the flags in your license

Licenses are typically issued for specific hosts. This means you must start the q prompt and perform the license check on the intended host(s). To do so without touching the existing license and potentially impacting a running environment, copy the new license to a temporary location first, for example ~/licnew/k4.lic. Then start the q prompt as follows: 

QLIC=~/licnew q

Starting q may fail because the new license is invalid. Once in the q prompt, run .z.l. The command returns the license information, including the feature flags. To see just the flags, run .z.l[4].

If a flag you need is missing, contact KX to have your license reissued. Tell KX which features you use, so that KX can include the correct flags.

Install a license

Each host in your deployment has its own copy of the license at $KXS_ROOT/lic/k4.lic, and KX Sensors processes read the license from there. The installer copies the license to each host for you. To install a license with the installer:

  1. Place your license file, k4.lic, in the license directory of your installation bundle:

    kxs-bundle-<bundle-name>/license/k4.lic

    The directory must contain one .lic file. If it doesn't contain any, the installer stops with an error.

  2. Run the KX Sensors installer as described in your deployment guide. For each host, the installer copies the license file into $KXS_ROOT/lic and sets QLIC in $KXS_ROOT/packages/kxsenv to $KXS_ROOT/lic.

  3. Check the flags in your license to confirm that the license includes the flags you need.

The installer moves the file without renaming it, so the file keeps the name it has in the license directory. Don't rename the license file that KX issues to you.

Replace a license before it expires

Replace your license before it expires to avoid disruptions. Running processes keep working after the license expires, but a process that stops can't start again with an expired license.

To find out when your license expires, start a q prompt and run .z.l[1].

Complete the following on each host to replace your license:

  1. Back up the existing license file:

    cp $KXS_ROOT/lic/k4.lic $KXS_ROOT/lic/k4.lic.bak

  2. Make a new folder ~/licnew and copy the new license file to it

  3. Check the flags in your license to confirm that the new license is valid and includes the flags you need. If the check fails in any way, obtain the right license first, then retry from step 1.

  4. Now that you've checked the new license, move it to replace the old license: 

    mv ~/licnew/k4.lic $KXS_ROOT/lic/
rmdir ~/licnew

  5. q processes check the license only when they start. An invalid license causes no errors until you restart the processes. You may restart your node(s) to proactively validate everything starts as expected. In a multi-node cluster, do so in a rolling fashion to avoid disruptions. For more information, see Start and stop nodes individually and Start and stop service class instances.

If a license has already expired, follow the procedure in Replace a license before it expires to install a valid license and run kxsctl start system to start any processes that failed to start.

Troubleshooting

Symptom Likely cause Resolution
A process fails to start with 'license error: cores The license limits the number of cores, but the process has access to more cores than the license allows. Review the variable KXS_BASE_TASKSET in $KXS_ROOT/packages/kxsenv on each host. It must match the number of cores supported by your license: run .z.l[0] from a q prompt to check. For example, if licensed for 8, set KXS_BASE_TASKSET=1-8. Run kxsctl start system. For more information, see Tasksets.
A process fails to start with 'license error:host The license is restricted to a specific host or host name pattern, and the host that the process runs on doesn't match it. Get a license that matches the host, or run KX Sensors on a host that the license permits. To get a different license, contact KX.
A process fails to start with a license error The license has expired, is missing, or isn't in $KXS_ROOT/lic. The QLIC environment variable may be incorrect, or the license file isn't readable by the KX Sensors user. Install a valid license at $KXS_ROOT/lic/k4.lic. Confirm the QLIC environment variable is $KXS_ROOT/lic. Confirm permissions on the license file. Align your license format with your KX Sensors version.
A feature such as RT, KX Dashboards, or REST isn't available The license doesn't include the feature flag or the format doesn't match the KX Sensors version. Check the flags in your license, and request a license with any missing flags. Align your license format with your KX Sensors version.

License formats

KX licenses come in three formats. Feature flags have a long form and short form. Ensure your format is compatible with your KX Sensors version. Most customers have an old-format k4.lic.

Format Feature flag form Works with KX Sensors v3.2 and earlier (kdb+ 4.1) Works with KX Sensors v3.3 and later (KDB-X)
k4.lic (offline, no telemetry) Long, for example insights.app.rt Yes Yes
Old format kc.lic (online, requires internet connection to work, telemetry always on) Long, for example insights.app.rt Yes Yes, but without features such as RT; behaves like raw kdb+.
New format kc.lic (offline, telemetry configurable) Short, for example rt No. q fails to start with a license error. Yes

If your license is a kc.lic, use kc.lic in place of k4.lic in the procedures on this page.

Next steps