License a Change Automation node

Set one of the three sources, shown in the tabs below. Choose by how your fleet is managed rather than by preference.

Put the setting in one of three places:

• Defaults file: add the property to liquibase.properties in the directory you run Liquibase from, or to the file named by --defaults-file. It applies to every run that uses that file.

• Environment variable: set it in the shell, the CI pipeline, or the container environment. It applies wherever that environment is in effect.

• Command-line flag: add --license-endpoint-url, --license-file, or --license-key to a single command, such as liquibase --license-endpoint-url=your_license_url update. It applies to that run only.

Setting more than one source

You can set more than one. Liquibase always tries the endpoint first, wherever you set it, then the license file, then the license contents. If the endpoint cannot supply a license, because it cannot be reached and has no cached response, it refuses the node's service principal token, or it serves a license that fails verification, the run falls back to the next source you configured. The node does not print a message when this happens, so check the Source line as described in step 4. If a license file or license contents is refused, for example because it fails verification, the run is refused rather than trying the next source.

A node that reads its license from the license endpoint reports the databases it acts on only when usage reporting is turned on. Without it, the node is licensed and runs normally, but its usage never reaches Liquibase Secure server, so the Utilization tab, the compliance checks, and the license alerts have nothing to measure.

Turn it on in the same place you set the license source. Use one of these:

liquibase.properties

Environment variable, macOS and Linux

Environment variable, Windows PowerShell

The node sends its usage to the address the license endpoint names, with the same service principal token it sends for its license.

Turn this on only on nodes that use the license endpoint. A node licensed from a file or license contents has no Liquibase Secure server to report to, so it prints a usage tracking warning on every run.

Usage is attributed to a tracking ID, which defaults to user@host. That default is useful on a workstation and much less useful on a build agent, where every run looks the same.

Set it in the same place you set the license source. Use one of these:

liquibase.properties

Environment variable, macOS and Linux

Environment variable, Windows PowerShell

Command-line flag

Be sure to:

• Replace your_tracking_id with a value identifying the team or pipeline. For example, payments-ci, platform-team

Run liquibase license status and read the Source line. This is the step that catches a node quietly using a file you forgot was there instead of the endpoint you just configured.

A licensed node reports:

Status: valid and Commands: allowed together mean Secure capabilities will run. Source names what Liquibase actually resolved, which is not always what you intended to configure.

On a node that uses the endpoint, Source names only the endpoint. If it names the license endpoint together with a file or environment variable, the endpoint did not supply a license and the node fell back to its own. The most common cause is a missing or rejected liquibase.platform.apiKey. See Troubleshoot licensing on Change Automation.

A licensed node runs Secure commands without a licensing message.

If this refuses with LB-LIC-0021, the node is not licensed. See Troubleshoot licensing on Change Automation.