Importing a new DRACOON Server license file

1Replace license file

The license file must be imported on all servers on which the DRACOON Core Service is operated. The same license file is used on all servers.

Place the new license file dracoon.lic on the DARCOON Core Service VM e.g. in the directory /tmp. The file is thus located in the path /tmp/dracoon.lic on the respective server. You can transfer the file e.g. via WinSCP (Windows) or SCP (Linux/Mac). Please note that transferring the content via copy + paste may be error-prone, as characters could be changed here and thus the signed content of the file could be changed and thus become invalid. If possible, always choose a transfer method that places the file unchanged on the server.

Show content of DRACOON Server license file

To view the contents of the license file, the package jq is required - so it must be installed first:

yum install -y jq

Afterwards, the contents of the license file can now be output with the following command:

cat /tmp/dracoon.lic | cut -d"." -f1,2 | sed 's/\./\n/g' | base64 --decode | jq

The output of the command looks something like this:

[root@demo01 ~]# cat /tmp/dracoon.lic | cut -d"." -f1,2 | sed 's/\./\n/g' | base64 --decode | jq
base64: invalid input
{
  "typ": "JWT",
  "alg": "RS256"
}
{
  "aud": "DRACOON",
  "tenants": [
    {
      "bookedCustomers": -1,
      "bookedStorage": -1,
      "validFrom": 1657152000,
      "domainNames": [
        "demo.server.dracoon.tld",
      ],
      "bookedUsers": 10,
      "validTo": 1751328000
    }
  ],
  "isUnlimited": false,
  "contactEmail": "contact@email-domain.tld",
  "iss": "DRACOON",
  "salesEmail": "contact@email-domain.tld",
  "iat": 1657192569
}

The output contains an error message ("base64: invalid input") at the beginning, but this can be ignored.

The essential information here are the following values:

The time is specified in the license file as an Epoch timestamp (the number of seconds since 01/01/1970 in the UTC time zone). Converting from an Epoch timestamp to a readable format is very easy under Linux:

date -d @<TIMESTAMP>

The output will look like this:

[root@demo01 ~]# date -d @1657192569
Thu Jul  7 11:16:09 UTC 2022
[root@demo01 ~]#

Backup existing license file

To be on the safe side, it is worth creating a backup (/etc/dracoon/dracoon.lic.bkp) of the previous license file (/etc/dracoon/dracoon.lic) before importing the new license file:

cp /etc/dracoon/dracoon.lic /etc/dracoon/dracoon.lic.bkp

Import new license file

The import of the license file is done by copying the new license file from /tmp/dracoon.lic to the target location /etc/dracoon/dracoon.lic. The DRACOON Core Service recognizes this change and reads the new license file automatically.

cp /tmp/dracoon.lic /etc/dracoon/dracoon.lic
touch /etc/dracoon/dracoon.lic

The system will ask you after running the command if the existing /etc/dracoon/dracoon.lic file should be overwritten. Please confirm this by typing "y" and then pressing the Enter key.

To ensure that the DRACOON license file can be read only by the DRACOON Core Service, the permission on the file should be assigned accordingly:

chown root:dc-core-svc /etc/dracoon/dracoon.lic
chmod 640 /etc/dracoon/dracoon.lic

2Preparations for customizing user licenses

For the next step you need a service token suitable for the client for the /provisioning API of DRACOON. If you do not yet have this information, it must first be read from the database. For this you need the following information about your DRACOON environment, which you must insert at the appropriate places in the provided commands:

Find X-Sds service token

The X-Sds service token is needed to manage the customers of a client. There are one or more tokens per client in the database. Normally, however, only one token is generated here when a client is added. You can read this token as follows:

mysql -u<db_user> -p<db_pass> -e "SELECT token, service_name FROM <default_db>.authorized_services;"

The result shows you a token in the column "token" and a free text in the column "service_name", which normally allows you to assign the token to the clients, if you use more than one client. If you have only one client, normally there will be only one token.

3Verify the license validity

curl -X GET "https://<Ihre_DRACOON_domain>/api/v4/provisioning/check_license" -H "accept: application/json" -H "X-Sds-Service-Token: xxxx"

You can get the "X-Sds service token: xxxx" via the previously mentioned step in the "Preparations for customizing user licenses" guide.

Alternatively, this is also possible via the Swagger Proxy, which is the documentation of the DRACOON API. To do this, call the following URL in the browser: https://<your_DRACOON_domain>/api/swagger-ui/index.html?configUrl=/api/spec_v4/swagger-config#/provisioning/checkLicense
Click the "Try it out" button, enter the client's service token in the "X-Sds service token" field that appears, and click the blue "Execute" button. The output will then return the status of the license:

{
  "validFrom": "2022-09-22T13:04:01.150Z",
  "validTo": "2022-09-22T13:04:01.150Z",
  "state": "valid"
}

4Adjust the number of user licenses

If you have only imported the new license file to extend the license period, you can ignore this chapter. In this chapter we describe how the number of users in a DRACOON tenant or customer is adjusted. This is necessary e.g. in case of a license extension or reduction.

The DRACOON Core Service does not automatically take over the number of allowed users from the license file. This is not possible, because the license file is valid on the level of the DRACOON Tenants (clients), but the users within a Tenant can be divided to several Customers. The number of user licenses (bookedUsers) is therefore only an upper limit at the tenant level.

Option 1: DRACOON Server Provisioning Tool

The DRACOON Server Provisioning Tool provided by DRACOON allows the management of Tenant and Customer via a Windows tool with graphical interface.

The documentation of the tool is available here:

   DRACOON Server Provisioning Admin Tool

Option 2: DRACOON Server http REST API

The DRACOON Server http REST API is available on each installation at the address https://<your.dracoon.domain.tld>/api/.

The API area /provisioning allows the management of customers within the respective client.

A customer is customized using the API endpoint PUT /api/v4/provisioning/customers/{customer_id}

A JSON array containing the new values is passed to this API. For example, to customize the number of maximum users in a Customer, the following array is passed:

{
  "userMax": <USER_ANZAHL>
}

The REST API can be used either through a Linux tool such as curl or through the Swagger proxy, which is accessible at https://<your.dracoon.domain.tld>/api/.

To use the /provisioning API endpoints, the X-Sds service token is required.