Managing the LICENSE file

Document updated on Mar 13, 2024

To run the Enterprise software, you must provide a valid license. The license file comes in an email containing the download link. The file is named LICENSE by default (no extension), although you can change its location and name as long as you let KrakenD know.

When the license file is expired, incorrect, or missing, KrakenD won’t start.

You can run krakend license to see if the installed LICENSE file is valid.

License file requirements

To start KrakenD Enterprise without seeing an error, make sure that:

• The file /etc/krakend/LICENSE (or the license file you have set) exists
• The license file is a plain text file and contains the certificate we gave you (it looks like a PEM file)
• You have not edited the contents of the file, and includes the surrounding -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.

Checking the license

The command krakend license and several of its subcommands help you validate the installed LICENSE file. Use krakend license --help for all the list of available subcommands and help.

The krakend license command exits either with a:

• non-zero status code and a KO: message string when the license is not valid or
• zero status code and an OK: string when the file is valid in the requested time.

All license files start and end on the agreed dates at 00:00 UTC.

For example, to check the expiration date of your license, you can do the following:

$krakend license valid-until
OK: License is valid until 2024-02-01 00:00:00 +0000 UTC

Or to find out the relative time_

$krakend license valid-for
OK: License is valid for the next 71 days, 6 hours, and 1 minutes

The following additional commands will help you check the license.

Is the LICENSE valid right now?

Execute the following command to know if your license is valid right now (although it could be invalid in the next second):

$krakend license
OK: License is still valid

You can also check an arbitrary file name passing the --license flag.

$krakend license --license /path/to/devel_license
OK: License is still valid

When the license is invalid, you’ll see the reason:

$krakend license
KO: x509: certificate has expired or is not yet valid: current time 2023-11-16T15:24:48+01:00 is after 2023-08-31T00:00:00Z

KrakenD Licensee

For a valid license, you can retrieve who is the licensee:

$krakend license licensee
ACME Inc.

For an invalid license, you won’t have any information.

Days left

Similarly, you can get the remaining days of a license as follows:

$krakend license days-left
OK: License has 71 days remaining

Automated license expiration checking

Because the command uses exit codes, you can include the license command in your automation and abort a pipeline when the license is expired or about to expire.

The command can check a license now or at a time in the future. Use the subcommand valid-for to determine if the license will remain valid after many hours or days. Use a numeric followed by h or d and no spaces. For instance:

$krakend license valid-for 90d
KO: License will be invalid in 71 days, 5 hours, and 49 minutes

Checking a relative date is probably the most convenient way to set this up quickly in a pipeline, but you can also check an absolute date using valid-until. For instance:

$krakend license valid-until 2024-11-10
KO: License will be invalid before 2024-11-10

Notice that the date format is yyyy-mm-dd.

The LICENSE file is a certificate

Because our LICENSE file is a regular certificate, you can use openssl to play with it.

For instance, you can execute openssl x509 -in LICENSE -text -noout to get all the information.

Change the location of the LICENSE

The LICENSE file is automatically loaded from /etc/krakend/LICENSE, although you can rename this file and change its location using two different methods:

1. Set an environment variable KRAKEND_LICENSE_PATH, for instance, KRAKEND_LICENSE_PATH=/path/to/prod_license.crt. As long as the content inside is valid, the path or extension you set (if any) does not matter.
2. Passing the --license or -l flags when running the application. For instance:

$krakend run -c krakend.json --license /my/dir/DEVELOPMENT_LICENSE

The flag --license takes precedence if you also set the environment variable KRAKEND_LICENSE_PATH.

How the license path is resolved

When you don’t change the location of the license with the environment variable or the flag, KrakenD internally looks for ./LICENSE. Because KrakenD’s working directory is /etc/krakend, the file is resolved to /etc/krakend/LICENSE. If, for whatever reason, you change the container’s working dir, the LICENSE must be changed to the exact location.

For instance, if you have a custom Dockerfile like this one:

FROM krakend/krakend-ee:2.6

WORKDIR /vault
COPY LICENSE .

When you change the working directory, all relative paths move to the new base directory, and when KrakenD starts, it loads the license from /vault/LICENSE (as well as any other external file referenced in the configuration relatively).

Storing the LICENSE in the Docker image

See Generating a Docker artifact

Storing the LICENSE in Secret managers

You can store your LICENSE in any secret manager of your choice if you want to. However, ensure the line breaks are respected when retrieving them again.

AWS Secrets Manager

One of the particularities of AWS Secrets Manager is that it might have problems when storing multiline contents. Therefore, we recommend keeping the LICENSE content in base64 format when working with AWS in plain text.

You can create an AWS secret with your license with this command:

$aws secretsmanager create-secret --name krakend-valid_trough-2023_05_22 --secret-string "$(base64 LICENSE)"
{
    "Name": "krakend-valid_trough-2026_05_22",
    "ARN": "arn:aws:secretsmanager:eu-west-1:052351007912:secret:krakend-valid_trough-2026_05_22-OISgD6",
    "VersionId": "59f7c317-989a-4219-bdd2-b79bead69dd4"
}

Notice that we have added the license’s expiration date to the secret name. A practice like this will help you quickly realize the expiration date of any license without testing.

You can later retrieve the license file in your pipeline file with:

$aws secretsmanager get-secret-value --secret-id krakend-valid_trough-2026_05_22 --query 'SecretString' --output text | base64 -d > LICENSE

Note: Depending on your computer’s operative system, the decoding of base64 might be base64 -D instead of base64 -d

What happens when the license expires?

Any running processes will shut down when the KrakenD Enterprise license expires.

The KrakenD sales team is always in touch before this happens to work on the next renewal.

Suppose you no longer want to be an Enterprise customer. In that case, you can downgrade to KrakenD Community very quickly and run in the open-source mode without the Enterprise functionalities.

Updating your license

When your license renewal comes, you must replace the /etc/krakend/LICENSE with the new content in your servers running KrakenD and restart KrakenD. That’s all!