The Qt License Service

Coco uses the Qt License Server system for license management. It consists of the following components:

• A License Server that provisions the licenses.
• A License Service program that acquires the licenses and caches them for use by the Coco programs locally.
• A License Client that uses the licenses, which is usually a Coco program.

The License Service resides on the same machine as the License Client, while the License Server is in general on a separate machine.

The default Qt License Server is hosted online at https://qls.qt.io, but a customer can also set up an on-premise License Server.

The setup of the License Service depends on the Coco version and whether there is already a Qt system installed:

• If there is already a Qt installation with a commercial license on the machine on which Coco runs, then Coco will use the License Service of the Qt installation.
• If no such installation exists, a stand-alone Coco installation can use the License Service tools that are bundled with it.
• Legacy systems (before Coco 7.4.0) cannot use the Qt License Service directly. For them, a separate cocolicserver package contains a special version of the cocolicserver program that translates Qt licenses to the old format.

Using an existing License Service

If there is already a License Service running, Coco will use it, as long as the License Sevice has a high enough version number.

When in doubt, do the following:

1. Print out the version info:

   Qt/Tools/LicenseService/qtlicd(.exe) --version

   This should show at least version 3.5.0.

2. If that's not the case, run the Qt Maintenance Tool, select Update components and follow the instructions.
3. Repeat step 1 to check the version number.

Now the Coco programs should be able to find the existing License Service installation.

To verify that a Qt license could be acquired, run

cocolic --check

It should output your license data and not "License is invalid".

Using the bundled License Service

We only describe here the simplest setup, the "on-demand" launch of the Qt License Service. This means that the License Service is started automatically when a Coco program needs a license, and stopped after some time when it is no longer needed. For other kinds of setup see the license service documentation.

Setup the License Service using cocolic

The quickest way to setup the bundled license-service is to use cocolic. Run the following command and follow the prompts on the screen:

cocolic --setup-qls

Then run the following command to verify that a license was acquired successfully:

cocolic --check

Setup the License Service manually

The License Service can also be set up manually by directly invoking the License Service program qtlicd and the setup program qtlicensetool.

In Coco, the License service programs are in the subdirectory license-service of the Coco installation.

• Under Linux, this directory is /opt/SquishCoco/license-service.
• Under macOS, it is /Applications/SquishCoco/license-service.
• Under Windows, it is %SQUISHCOCO%\license-service.

In the following section, this directory is abbreviated as license-service.

1. Register qtlicd so that it is started automatically as on-demand service, with

   license-service/qtlicd(.exe) --register

   qtlicd then creates a configuration directory.

   • Under Linux, this directory is ~/.local/share/Qt/qtlicd.
   • Under macOS, it is $HOME/Library/Application Support/Qt/qtlicd.
   • Under Windows, it is C:\Users\<user>\AppData\Roaming\Qt\qtlicd.

   A file installations.ini is created in this directory, which contains the information about the License Service installations on this machine.

2. Configure the license service.

   Accept terms and conditions of the Qt License Service, with

   license-service/qtlicensetool(.exe) --accept-terms-and-conditions

   If you use your own on-premise Qt License Server, run the following command:

   license-service/qtlicensetool(.exe) --set-server-address <license server URL>

   Any of these steps automatically creates qtlicd.ini and other files in the configuration directory. Alternatively, you may also manually create the configuration directory and copy the file license-service/qtlicd.ini into it. Then you could manually edit the following entries in qtlicd.ini:

   terms_and_conditions_accepted=true
   server_addr=<license server URL>

   The other parameters in qtlicd.ini are described in the Qt License Service configuration documentation page but it is rarely necessary to modify them.

3. Login with your Qt account to acquire a license.

   Note: This step is necessary if you want to use the central Qt License Server. Skip this step if you will be using an on-premise Qt License Server.

   Run

   license-service/qtlicensetool(.exe) -l

   You are then prompted for your Qt account email address and its password.

   As of License Service 3.5.0, it is also possible to specify the account email and the password with environment variables QT_ACCOUNT_LOGIN_EMAIL and QT_ACCOUNT_LOGIN_PASSWORD before running the command above.

   export QT_ACCOUNT_LOGIN_EMAIL=<email>
   export QT_ACCOUNT_LOGIN_PASSWORD=<password>
   license-service/qtlicensetool(.exe) -l

   The email address and password are then read from the environment variables instead of being prompted for. This is useful when qtlicensetool is run from a script without user interaction.

   Warning: This method could expose your password in logs and shell history. Use with care!

4. Run

   cocolic --check

   to verify that the license was acquired successfully.

Setup the License Service without user interaction

The steps in the previous section can also be done without user interaction. They can be used in a script to set up the License Service on a machine where Coco is installed, for example in a continuous integration environment.

Under Linux or macOS, the script will look like this:

SQUISHCOCO=<path to SquishCoco installation>

$SQUISHCOCO/bin/cocolic --set-license-provider=QLS
$SQUISHCOCO/license-service/qtlicd --register
$SQUISHCOCO/license-service/qtlicensetool --accept-terms-and-conditions

# If you use the Qt License Service:
export QT_ACCOUNT_LOGIN_EMAIL=<email>
export QT_ACCOUNT_LOGIN_PASSWORD=<password>
$SQUISHCOCO/license-service/qtlicensetool -l

# If you use your own license server:
# $SQUISHCOCO/license-service/qtlicensetool --set-server-address <license server URL>

$SQUISHCOCO/bin/cocolic --check

Under Windows, where the variable SQUISHCOCO is set by the installer, use the following commands:

"%SQUISHCOCO%\cocolic" --set-license-provider=QLS
"%SQUISHCOCO%\license-service\qtlicd" --register
"%SQUISHCOCO%\license-service\qtlicensetool" --accept-terms-and-conditions

REM If you use the Qt License Service:
set QT_ACCOUNT_LOGIN_EMAIL=<email>
set QT_ACCOUNT_LOGIN_PASSWORD=<password>
"%SQUISHCOCO%\license-service\qtlicensetool" -l

REM If you use your own license server:
REM "%SQUISHCOCO%\license-service\qtlicensetool" --set-server-address <license server URL>

"%SQUISHCOCO%\cocolic" --check

Adapt the scripts to your needs.

Troubleshooting

If you encounter any issues, you may check the following documentation pages:

• Troubleshooting Qt License Service
• Troubleshooting Qt License Server

You may also send a support request via your Qt Account, together with the relevant log files.