License Management

The main features of this opsi extension are:

A licensing model defines who may use a software in which form (see section Configuring the Licensing Model). There are various approaches as to how the software manufacturers handle this:

If the opsi server controls the allocation of licenses, it is ensured that the license and if necessary the key are released again when the software is uninstalled. Furthermore, the allocation of licenses can also be done manually or even script-controlled, e.g. if a license has not been distributed with opsi.

License management is a complex topic. To represent it, opsi has to implement a relatively complex database model to manage the licenses and their keys. For a better overview the following diagram represents the involved tables. The blue line marks the border between tables which are automatically generated by the software audit functions and tables with data that is collected or assigned specifically for license management. Only the license pool table has connections to both spheres. This fact hints at the importance of this construct.

The diagram also shows the meaning of license pools, which the License Pools section explains in detail.

The management interface opsi-configed offers a separate window for license management. You can access the dialog via the Licenses button in the main window. The prerequisite is that the extension is installed and activated. To check this, go to the Help / Modules menu in the main window.

The license management dialog box displays six tabs at the top:

The following sections explain the individual dialogs and their various features.

For each type of license you want to manage with this extension, you need to set up a separate license pool. This pool describes the summary of rights, which are needed to install a certain kind of software legally. The license pool is the center of all opsi license management activities:

At the very top of the License pools dialog you can see a two-column table listing all available license pools. You can edit the description field and enter your own descriptions there.

Further editing functions can be accessed via the context menu of the right mouse button. Use the entries displayed there to create a new pool, delete an existing one, save or discard the changes, and reload the data.

When creating a new pool, i.e. when creating a new table row, enter a (unique) licensePoolId in the corresponding field, for example pool_for_x.

Unlike the description, you can edit the pool ID only until you save it for the first time. After that, it cannot be changed because it’s used as the primary key. Deleting an entry is only possible if there is no reference to this key in other tables. Recursive search for such references is currently not supported.

Each editing operation changes the status display of the two buttons OK and Cancel. The green check mark of the OK button turns red and the Cancel button is enabled. Press one of the two buttons or select the corresponding entry from the context menu of the right mouse button to save or cancel your changes.

In general, only one license pool belongs to an opsi product which installs a software requiring a license and which is to use the license management. The required licenses are drawn from this pool. It’s possible, though, that several products refer to the same license pool if those are variants of the same software. For example, the products win10-x64 and opsi-local-image-win10-x64 both use the pool p_win10-x64.

The situation is less clear, if an opsi product installs several software products requiring licenses from several license pools. Assuming that a package called Design-Programs includes Adobe Photoshop and Adobe Writer, the opsi product must request licenses from two different pools. Basically, these assignments are based on an n:m scheme.

The second table in the License pools tab (see [licensemanagement-licensepools.png]) manages the relationship between the license pools and the product IDs of the opsi products. Click on the licensePoolId or productId column title to sort the table. This way you can show the connections between opsi products and a license pool or all license pools assigned to an opsi product.

You can create a new entry, i.e. a new assignment of a license pool to a product ID, via the context menu of the right mouse button. After clicking into the table field you will see a list of available options.

The lower half of the License pools tab (see [licensemanagement-licensepools.png]) represents the correlation between license pools and the installed software on the opsi clients, either installed with opsi tools or in another way. In the individual columns you can see a unique ID, which is constructed from combining all attributes and acts as a unique key. This is followed by information about the software, including the name, the version number, the operating system, the architecture etc.

The opsi software audit determines the values (see section Products for Hardware and Software Audit: hwaudit and swaudit); it retrieves information from the registry and reports it back to the opsi server. The table SOFTWARE_CONFIG of the opsi database stores the values for each client. If not already present, they are added to the table SOFTWARE. This forms the basis for the table displayed in the license management.

Two different views determine which data you can see in the table at the bottom of the License pools dialog:

So here you can see all assignments of software items (from the database table SOFTWARE) to a license pool (table LICENSE_POOL). All entries belonging to the license pool selected in the upper table appear as highlighted rows with a colored background. This allocation is precisely the data from the AUDIT_SOFTWARE_TO_LICENSE_POOL table.

A change in the rows highlighted in blue means a change in data. Therefore, the functions for navigating in the table behave differently than usual. A red asterisk at the beginning of the line marks the location of the cursor.

In order to reposition the cursor, you have the following options:

By allocating software items to license pools, you have already established the base for a compliance check required by Microsoft. This is how it works: Use the mouse to mark the software items in a pool. To determine the total number of installations assigned to a pool, open the Statistics tab (see section Statistics).

Use the context menu of the right mouse button to access functions for filtering the assigned software items. You can either display all items or only the selected ones.

This can be helpful since the rows of assigned software items are not necessarily consecutive in the software table. Select Show only marked items, and the view changes:

Alternatively, use the filter icon next to the search field. When a filter is active, the icon appears crossed out.

When the software manufacturer distributes a new version, an update or a patch, the new variant also receives a new Windows software ID and therefore shows up as a new entry in the software table (with a new ID). In most cases, the new software can be treated the same way as far as the license is concerned. If a license agreement was required for the old version, one probably exists for the new one. This means that the need for licensing for both editions must be registered in the same license pool. Coverage is then organized via the common license pool.

When rolling out new versions, you should therefore remember to add an assignment to the correct license pool. Of course, there is also software which installs updates without your intervention. As a result, the correct allocation may be missing after the update. That is why the management interface opsi-configed (since version 4.1.9.8) offers a separate dialog to simplify the completion of allocations. You can open the window by clicking on the Name → Pool button in the lower half of the License pools tab.

The dialog displays two auxiliary tables. If you have activated the default setting Show all software names before opening that window, the first column of the first table shows the names in alphabetical order. The second column lists all IDs associated with the respective name (although the first part of the ID, i.e. the exact software name, is not repeated for simplicity reasons).

The second table lists the IDs for the name selected in the first table. For each ID, it shows whether there is an allocation to a license pool and what it is called. This allows you to standardize the license pool assignments:

The third option (Show software without any assignments) allows you to search for any forgotten license assignments.

Of course, it is possible to assign all installed applications to a license pool — including free software. If you then install a new software or a new version of an existing one, previously unassigned software items are easily identifiable.

opsi-configed provides additional display options for such scenarios (see also Software Table: configuring the view):

Assuming you have assigned all software to a license pool until now, the individual steps look like this:

The steps are different if you want to distribute arbitrary, not yet assigned software items to license pools:

First, let’s clarify some important terms:

Licensing means the actual deployment of a permission to use software by installing the software on a client. Sometimes, but not always, this includes using a special license key.

The software license is the permission to install and use a software as defined by the license contract. In the opsi database the software license corresponds to the licensing right and is identified by a softwareLicenseId. The licensing model describes the licensing right in more detail and determines, for example, for how many computers and how long a license is valid. The license contract states and documents the licensing right in the legal sense.

A licensing option describes the possibility to apply a licensing right for a specific license pool. opsi defines the licensing option by a combination of softwareLicenseId and licensePoolId. If required, this includes the actual licenseKey.

Finally, the license usage documents the use of a license by assigning the licensing option to a client, it’s the completed and authorized licensing of a software installation. The description is composed of softwareLicenseId, licensePoolId, and hostId (unique name of the opsi client). If required, it also notes the licenseKey.

After you have decided on a license pool for which you want to create a licensing option, you select the license contract. In the table Select or enter license contract you can choose an existing contract or create a new contract record.

The first column shows the licenseContractId, which is used to identify the license contract in the database. This is followed by information about the contract partner (partner), the conclusion date (conclusionDate), the notification date (notificationDate) and the expiration date (expirationDate). The last field (notes) can hold some additional information. For example, here you can write down the location of the documents belonging to the contract or a file number.

Use the context menu of the right mouse button to create a new record. A new unique ID (based on the current date and time stamp) is automatically created. You can use the default setting if purchasing the software implies the license contract or if the contract is documented and traceable in some other way. Otherwise, the data can and should be edited to ensure orderly tracking of the underlying contract, for example, by entering a file number in the notes field.

In the Configure license section of the New license tab, you can register the licensing model. Use one of the four buttons to select the licensing model:

In all four cases, the automatically generated data includes a unique ID (based on the current date and time stamp). You can accept or modify the default value. Depending on the license model you have chosen, you can adjust the other fields or not.

Hit the Send button to submit the data to the opsi service and to add it to the database. This will create records for a software license based on the selected contract and licensing option. You can see these at the very bottom of the tab in the Available license options section. After saving your changes, the table will be reloaded and the newly generated option will be automatically highlighted.

The following example shows how to configure a license with downgrade option. In other words, instead of the purchased software, the preceding version may also be installed. Thus, an existing license key may be used for an additional installation for which it was not originally legitimized.

The opsi model maps this construction as follows: on the tab New license you register the license. As a result, you receive a new licensing option (displayed in the lower table), which is based on a likewise newly created licensing right (softwareLicenseId). You need this value for the following steps. Either you copy the value to the clipboard or you look for it in the second table on the tab Edit licenses.

Next, connect the existing licensing right to another license pool:

If you have configured a downgrade option (see section Example: Configuring a Downgrade Option), the Usage of licenses, overview table represents that as well. A downgrade license grants one licensing option each for (at least) two license pools. Only one of the two can actually be used. Therefore, as soon as a licensing option is used, the value in the remaining_opsi column in both rows decreases by 1. So apparently the number of available licenses decreases by 2—​this is completely correct, however, and reflects the actual authorization situation.

There are two functions for license management (see the section (String) Functions for Licence Management [W/L/M]):

Instead of the license pool ID, you can specify the product ID or a Windows software ID as a parameter.

You call the service methods for example with opsi-admin; parameters marked with \* are optional:

The method creates a new license contract record with the ID licenseContractId or edits an existing one. If you don’t specify the ID, it will be generated automatically. The two parameters partner (contract partner) and notes (notes on the contract) are user-defined strings. Specify conclusionDate (date of conclusion of the contract), notificationDate (reminder) and expirationDate in the format YYY-MM-DD, e.g. 2023-02-28.

You can use the string functions getLastServiceErrorClass and getLastServiceErrorMessage to react to an error, e.g. if no free license is available anymore:

The error class LicenseMissingError is returned if a license is requested but not available. The error class LicenseConfigurationError is returned if the configuration does not allow a unique assignment of a license pool to a software.