- Task
- Version ยท 6.0.2
- Manage
License a Change Automation node
Last updated: November 17, 2026
Give a Change Automation node a license using any one of three sources, then confirm which one it actually used.
Before you begin
Liquibase Secure installed on the node.
One of the following: the URL of the license endpoint served by Liquibase Secure server together with a service principal token, or a base, renewal, or consolidated license file Liquibase sent you.
Network access from the node to the endpoint, if you are using one.
Procedure
Configure a license source
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.propertiesin 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-keyto a single command, such asliquibase --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. Every command then prints a WARNING: line that names why the endpoint was skipped, and the Source line in step 5 shows which license was used. 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.
Keeping the endpoint settings in a secrets manager
The license endpoint URL in liquibase.license.endpointUrl and the access token in liquibase.platform.apiKey can be secrets-manager references, in any of the three places. So can liquibase.license.cacheFile and liquibase.license.endpointTimeoutSeconds. Liquibase reads these four settings before the node has a license. Every other setting held in a secrets manager is read only after the node is licensed.
If one of the four cannot be resolved, the run is refused with LB-LIC-0029. The message names the setting and shows the secrets manager's own error. The node does not fall back to a license file or license contents in that case.
If you use a personal access token rather than a service principal's token, its owner needs the Read the license access endpoint permission. A service principal has it by default.
Turn on usage reporting
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
liquibase.license.tracking.enabled=trueEnvironment 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.
Set a tracking ID
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
liquibase.license.tracking.trackingId=your_tracking_idEnvironment variable, macOS and Linux
Environment variable, Windows PowerShell
Command-line flag
liquibase --license-tracking-tracking-id=your_tracking_id updateBe sure to:
Replace
your_tracking_idwith a value identifying the team or pipeline. For example,payments-ci,platform-team
(Optional) Choose what happens when usage is not accepted
After each run, the node sends its usage to the usage tracking server. A node licensed from the license endpoint sends it to the address the license response names, on Liquibase Secure server. A node licensed from a file, license contents, or a pre-6 license key, or one whose license response names no tracking address, sends it to the address in liquibase.license.tracking.url, which need not be Liquibase Secure server.
By default, if that usage is not accepted, the run ends with one warning and that run's usage is not reported. Two settings change this, and each works on its own:
liquibase.license.tracking.spoolDirnames a directory where Liquibase saves usage it could not deliver, and sends it again on the next run.liquibase.license.tracking.requiredfails the run instead of warning.
Set them in the same place you set the license source. Use one of these:
liquibase.properties
liquibase.license.tracking.spoolDir=your_spool_dir
liquibase.license.tracking.required=trueEnvironment variable, macOS and Linux
Environment variable, Windows PowerShell
Command-line flag
Be sure to:
Replace
your_spool_dirwith a directory only the account running Liquibase can read. For example,/var/lib/liquibase/usage-spool,C:\liquibase\usage-spoolLeave out the setting you do not need.
With spoolDir set, usage that could not be delivered, because the server could not be reached, timed out, or answered with a server error, is saved in that directory. At the start of the next run, Liquibase sends the saved usage again, oldest first. Liquibase removes each item the server accepts and deletes each item it rejects, so a rejected item is not sent again. If an item still cannot be delivered, it and every item saved after it wait for the following run. Usage the server rejects, such as a report refused with HTTP 401, is not saved, because sending it again would be rejected the same way. Without spoolDir, nothing is kept.
With required set to true, a run whose usage the server does not accept fails with LB-TRK-0001 and exit code 70 instead of printing the warning. Usage is sent after the command finishes, so the database changes the run made stay in place. Only the run's result changes. If the command itself failed, you see the command's own error, and the tracking failure is only a warning.
Usage is sent as payload version 2, which never includes a license key. Set liquibase.license.tracking.payloadVersion=1 only if the server receiving usage does not read version 2. Version 1 is the format Liquibase 5 sends, and it includes a pre-6 license key when one is configured, so a spoolDir directory holding version 1 usage needs the same care as the key itself.
Confirm which source was used
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.
liquibase license statusA 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 a file or environment variable and a License endpoint line follows it, the endpoint did not supply a license and the node fell back to its own. That line gives the reason. The most common cause is a missing or rejected liquibase.platform.apiKey. See Troubleshoot licensing on Change Automation.
Confirm a Secure command runs
A licensed node runs Secure commands without a licensing message.
liquibase checks showIf this refuses with LB-LIC-0021, the node is not licensed. See Troubleshoot licensing on Change Automation.