Geneos Licence Daemon - Technical Reference

Licensable Features

Certain features of Geneos require a licence in order to be used. These features can be divided into the following broad categories:

• Being able to run Geneos binaries such as Gateways and Netprobes.
• Being able to use certain Gateway features such as database logging or compute engine.
• Being able to use instances of certain Netprobe plugins.

The Licence Daemon

The Licence Daemon is a Geneos process that other Geneos processes connect to in order to acquire permissions to use certain Geneos features.

Features related to netprobes such as the ability to run certain plug-ins are licensed through Gateways. Netprobes do not directly connect to the Licence Daemon.

The Licence Daemon refers to a single licence file. The licence file contains information about the number of each type of Geneos feature that a particular client installation is allowed to use. It is provided by ITRS and has an expiry date, after which it will no longer be valid.

Licence Requests

When a Geneos process requires a licence for a particular type of functionality, it sends a licence request to the licence daemon. This request is granted or denied based on available licences, current usage, and the mode that the licence daemon is running in.

Request can revoked or accepted at any time; For example, licence request that is at first granted can be later denied when the licence file expires.

When a licence is granted, the geneos component will enable the relevant functionality, and when the licence is revoked the geneos component will disable the relevant functionality.

Licence Daemon Modes

The licence daemon can run in one of two modes; ENFORCING or MONITORING.

In ENFORCING mode the licence daemon will only grant licences if there are sufficient unused licences of the to match the request.

In MONITORING mode the licence daemon will always grant the request. This mode is used to monitor the licences being used rather than to lock a site down to an exact number of licences.

The mode of the licence daemon is controlled by a setting in the licence file obtained from ITRS.

Licensing Reports

Once the licence daemon is running, you can see reports on the usage and availability of licences. These views can be seen via a Gateway using the Licence Usage Gateway plugin and by going to the web page that will be served up by the licence daemon (see Monitoring). The licence daemon also provides a pair of CSV files, one containing the summary of licence usage, while the other contains a detailed breakdown of the licence usage (see Reporting).

Operating System support

Please refer to the Geneos Compatibility Matrix for the list of supported platforms.

When Security-Enhanced Linux (SELinux) is running in Enforcing mode, it may deny certain functions of Geneos depending on the implemented configurations and policies.

To see which functions SELinux denies, check the audit log. The log is typically located in /var/log/audit.log, where the log type entry is AVC. The audit log provides the details of any denied access. For example, denied connection to the TCP port.

If you experience issues related to this mode, you may opt to disable SELinux, or create policy modules to grant the required access. Please contact your administrator or security team for assistance.

Installation considerations

/usr/local/geneos/licd

Installing a Licence Daemon

This section describes how to install a licence daemon and run it so that Geneos processes can connect to it and request licenses.

licd.<platform>

Acquiring a Licence File

The licence file will be provided by ITRS. ITRS must be provided with the hostid and hostname of the server where the licence daemon will run.

If you run the licence daemon without a licence file it will output the hostid and hostname of the server to the licence daemon log.

Changing the Licence File

To change the licence file:

1. Shut down the licence daemon.
   • This does not have any immediate effect on the Geneos functionality that was being licensed through this licence daemon. Geneos processes are made to retain their current licensing status in the event of being unable to connect to a licence daemon. See Licence Persistence for more discussion of licence persistence and the limitations of running geneos components when there is no licence daemon available.
2. Overwrite the current geneos.lic with its replacement.
3. Start up the licence daemon again.

At this point, the Geneos processes that were previously connecting to this licence daemon will reconnect and re-submit their licensing requests. The licence daemon will then attempt to service these requests using the licences found in the new licence file.

Viewing the contents of a Licence File

The most convenient way to view at the contents of the licence file is to look at the licence report in the licensing web front-end (see Reporting). The Overall table shows a list of the number of each licence tokens provided by ITRS and the top right shows the mode that the licence daemon is running in.

Expiry

Licence files have an expiry date. The expiry date of the current licence file can be seen in the licensing web front-end.

The licence is no longer be valid once the expiry date is reached. If the expiry date is reached on a licence file that is in use, instances of Geneos functionality having licences granted through the particular licence daemon will have their licences revoked and the functionality in question will stop working. Therefore a licence file nearing expiry should ideally be replaced before it expires.

It is important to monitor the time to expiry of the licences provided by ITRS. See Monitoring for a description of the best way to monitor the licence daemon.

Group Validation

One of the reasons for assigning licences to a group is that the licence daemon administrator may wish to ensure that licences required by one department are not used by another department. To ensure that grouping can provide this functionality, it is important that the number of licences assigned to groups by the licence daemon administrator do not exceed the number of overall licences provided by ITRS. If the licence daemon administrator configures too many licences in their group files, the licence daemon will not start. It will provide errors in its log file explaining which tokens have been over assigned.

When running in monitoring mode, there may be times when the licence daemon administrator wishes to exceed the number of licences provided. They may have reviewed Geneos usage and increased the number of components used. While there is no need to change the group assignments, it can be beneficial to have the group assignments reflect the usage in the departments so that it is clear when a department is over-using resources. The command line option -ignore-group-size-check allows the administrator to specify group preallocations that exceed the number of allocations in the licence file. (This can only be specified for licence daemons that are running in MONITORING mode).

Probe Licence Groups

It is also possible to set the licensing group on individual probes on a Gateway. This allows for the sharing of licences between departments.

Consider the following situation: a server needs to be monitored by both Department A and Department B and as such, both departments want to run Netprobes on that server. An unlimited number of Netprobes can be run on a single server, using one server licence. If both groups added one server licence to their own licensing group, that would require two server licences in the overall file, because licence tokens are assigned to a single group.

To solve this, an additional group A_and_B is configured on the licence daemon containing the server licence for that particular machine. In the gateway configurations for both departments, the licensing group is set to A_and_B. As such, both departments can guarantee monitoring of the server whilst still only using one server licence overall.

In summary: setting licensing group on a probe results in any licence requests for that probe and all its plugins being served by the daemon from the probe licensing group rather than the Gateway licensing group.

Configuration

The licence daemon looks for groups in a group directory located in licence daemon's working directory. This can be overridden using the -grouping-dir command line option (see Command Line Options).

Each grouping is stored in a separate file in the directory. The first line is "GROUP" followed by the name of the group that administrator wishes to allocate items for. The following lines are token names with values. As can be seen in examples in Licence Groups, * can be used to indicate that the number of tokens is unlimited. To make it easier to generate these files, the licence daemon can create a template for the administrator. Running licd with the -create-grouping-template command line option (see Command Line Options) will create a file containing all the tokens specified in the licence file. All that is required is to enter the group name in the first line of the file and to replace the '?' by the allocations for the group in question. Then move the file into the group directory. An example is shown below.

Group Template file generated by the licence daemon

GROUP [enter group name here]
<gateway> = ? # of *
<servers> = ? # of 100
<cpu> = ? # of 100
<hardware> = ? # of 100

To allocate licences to groups when the licence file provided by ITRS does not contain the tokens, it is necessary to use the command line option -ignore-group-size-check (see Command Line Options). This allows the number of licences allocated to the groups to exceed the number of licences allocated overall. This feature can only be used with licence files that configure MONITORING mode.

Errors and warnings

Typically, these inform the administrator of error and warning conditions that are encountered by the Licence Daemon.

For example, the following shows the log entry that would be written on start up if the Licence Daemon detects that another licence daemon is running on the same server.

<Fri Dec 03 19:03:05> ERROR: LicdSecurityPort Another License daemon is already running on this host - terminating

Typically, most error conditions related to the Licence Daemon would be encountered on start up, as in the case above. However, it may advisable to monitor this log file for the keywords ERROR and WARN in order to be informed of any error conditions that may be encountered during its normal operation.

Significant events

In addition to error conditions, the Licence Daemon log contains entries indicating significant events.

For example, the following shows the log entry that would be written when the current licence file expires.

<Fri Dec 03 20:01:47> INFO: LICD Licence ABC_Capital has expired. All components covered by this license are now unlicensed

Similarly, log entries would be written when Geneos processes connect and disconnect from the Licence Daemon.

Licence rejections

When the licence daemon rejects a licence request, a message is placed in the Licence Daemon log with details of the licence that was rejected.

For example, the following shows the log entry that would be written when a CPU sampler was rejected.

<Fri Dec 03 20:01:47>  INFO: LICD Requested Token [Binary:gateway:LicD Iteration Gateway 1 Class:plugin Item:cpu] is Unavailable

Gateway Data

The Gateway Data plug-in provides 4 fields related to licensing;

• licenceFile — If the Gateway is connected to a licence daemon (or reading from a licence cache) then this is the name of the licence file provided by ITRS. The name is embedded in the licence file. If the Gateway is using a temporary licence then this is the location of the temporary licence file.
• licenceExpiryDate — contains the expiry date of the licence provided by ITRS.
• licenseDaysRemaining — contains the number of days remaining on the licence.
• licensingMethod — returns the licensing method. It is one of Temporary Licence, Licence Daemon, or Licence Cache.

Gateway Data plugin views

Licence Usage View

The licence usage view allows monitoring of the licence usage. By default this plugin provides two views if it connects to a licence daemon with no groups configured.

• LicenceUsage — provides details of the licence status.
• Overall — provides a summary of all the licence tokens that have been used.

If the licence daemon is not running then the connected value in the LicenceUsage view will be set to NO and the Overall view is not created. However, if the licence daemon is stopped after the Gateway has started, the Overall view is maintained. The value of connected will be set to NO and the lastUpdateFromLICD stops being updated.

If the gateway is unable to obtain a license for the sampler, then the following error message is displayed:

ERROR: ProbeManager Sampler <sampler> in Managed Entity <managed entity> is unlicensed. 

The following are the possible reasons for such error:

• The license usage may be exceeded if you are adding new samplers.

• The license has expired.

• The gateway cannot connect to the Licence Daemon, which may be down because of network issues.

If groups are configured (see Licence Groups), more information is available. By default, the plugin shows a view for the Gateway licensing group instead of the Overall view. If any additional licensing groups are configured on individual Netprobes, the appropriate group view is also shown. If any of these the groups has not been configured on the licence daemon, the view for the Other group is shown instead. (Only one Other view is shown even if there are multiple licence groups on the Gateway that have not been configured on the licence daemon.)

Views for additional groups can also be shown via the plug-in configuration. In this case, the default views are not shown, only those configured. Any views explicitly configured for groups that do not exist on the daemon result in an empty view with an error in the samplingStatus.

By default, the plugin shows a view for each of the groups that the Gateway requests licences for. If a Gateway is in licencing group G1 and has probes in licensing group G2 and G3, then it requests views for G1, G2, and G3. The licence daemon interprets the requests and views for managed groups that it requests and returns the Other view for any non managed groups. Therefore if the Gateway requests G1, G2, and G3 but the licence daemon administrator has only configured G1 on the licence daemon, the views sent back are G1 and Other, giving 3 views on the plugin; LicenceUsage, G1, and Other.

For example, consider a licd configured with groups G1 and G2. A Gateway in G1 with probes in G2 and G3 and an empty plugin config would result in views displayed for G1, G2, and Other. If Overall, G2, and G3 were configured in the plugin, views would be created for each but with an error in G3 as it does not exist on the daemon.

Licence Usage plugin views (Licence Usage)

Licence Usage plugin views (Default - no groups in Licence Daemon)

Licence Usage plugin views (All groups)

Licence Usage plugin views (Default - My groups)

Suggested Rules

It is strongly suggested that a Gateway is used to monitor the licence daemon like any other application. The following are a set of useful rules that can be applied to the view Gateway Data plugin and Licence Usage plugin.

• Ensure the administrator is emailed when a licence is close to expiry: Target licenseDaysRemaining in the Licence Usage or Gateway Data plugins.
• Set Critical severity if the Gateway cannot connect to the licence daemon: Target licensingMethod in Gateway Data or connected in the Licence Usage plugin.
• Ensure that port, hostname, and licence name are as expected: Target the respective cells in the Licence Usage plugin.
• Ensure licence daemon mode is as expected: Target the mode headlines in any of the Licence Usage views. Normally this would be the Overall view for an administrator.
• Monitor when the number of licences run out or are exceeded: Target the cells in the Free column of the Licence Usage views.

Licences Report

The licences report shows the following information:

1. Name of the current licence file (the name given by ITRS to the specific client or client site that the licence has been created for).
2. Expiry date of the current licence file.
3. A table showing information related to each type of licence found in the licence file.

   Columns:

   1. Licence — Name for the particular type of licence. For example, the licence that allows you to run CPU plug-ins is called "cpu".
   2. Total — Number of licences for this type of provided. The column will say "Unlimited" instead of a number if unlimited licences of this type are available.
   3. Used — Number of licences that are currently being used.
   4. Free — Number of unused licences.

   Colours:

   • Green — The licence daemon is in Enforcement mode.
   • Amber — There are no more licences of this type.
   • Amber — The licence daemon is in Monitoring mode.
   • Red — More licences have been allocated than are specified in the licence file/group allocation.
   • Red — The licence has expired.

If the licence daemon has not be configured to preallocate licence tokens to groups, there will be one table called Overall. If the licence daemon has been configured to preallocate licence tokens to groups then there will be a table called Overall, one table for each group specified by the administrator, and a final group called Other. See Licence Groups for more information about licencing.

CSV Files

The Report web page provides two links that return CSV reports. These are:

• Summary — http://<host>:<port>/licensing/licences.csv
• Details — http://<host>:<port>/licensing/all_licences.csv

where host is the host on which the daemon is running and port is 7041 unless it has been manually specified on the licence daemon command line.

samplingStatus  OK
expiry  28-Feb-13
mode    ENFORCING
licenceName     LICD-TEST
rejectedRequests        1
Group   Token   Total   Used    Free
Overall cpu     1       1       0
Overall gateway Unlimited       1       Unlimited
Overall servers 5       2       3
Overall toolkit 1       0       1

samplingStatus,OK
expiry,28 February 2013
mode,ENFORCING
licenceName,LICD-TEST
rejectedRequests,1
Group,Token,Total,Used,Free
Overall,cpu,1,1,0
Overall,gateway,Unlimited,1,Unlimited
Overall,servers,5,2,3
Overall,toolkit,1,0,1

Req Number      Group    RequestingComponent                    Component               Item            Description             Number
1               G2       gateway:LicD Iteration Gateway 1       gateway_component       gateway                                 1
2               G2       gateway:LicD Iteration Gateway 1       binary                  netprobe        host1:19062 [ab32ed32]  1
3               Other    gateway:LicD Iteration Gateway 1       binary                  netprobe        host2:19064 [23deed32]  1
4               G2       gateway:LicD Iteration Gateway 1       plugin                  cpu             host1:19062 [ab32ed32]  1

Req Number, Group, RequestingComponent, Component, Item, Description, Number
1,G2,gateway:LicD Iteration Gateway 1,gateway_component,gateway,,1
2,G2,gateway:LicD Iteration Gateway 1,binary,netprobe,host1:19062 [ab32ed32],1
3,G2x,gateway:LicD Iteration Gateway 1,binary,netprobe,host2:19064 [23deed32],1
4,G2,gateway:LicD Iteration Gateway 1,plugin,cpu,host1:19062 [ab32ed32],1