Geneos Licence Daemon

Intended Audience Copied

This document is a reference guide and is aimed at administrators of the Geneos monitoring system. It is expected that readers will have some familiarity with the Geneos product. Readers are also expected to be familiar with UNIX command line operations.

Introduction Copied

Licensable Features Copied

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 or Collection Agent plugins.

The Licence Daemon Copied

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 Copied

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 Copied

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 Copied

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).

Demo mode Copied

You can run Geneos in a Demo mode without a license daemon to trial the software.

For more information, see Demo mode in Gateway Licensing.

Running the Licence Daemon Copied

Operating System support Copied

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 Copied

Beginning Geneos version 5.0.0, this component is only compatible with other Geneos components that are version 3.6.0 or higher. For more information, see the Geneos Compatibility Matrix.

Installation directory Copied

Select a directory to install and extract the files. For new installations the following directory is recommended:

/usr/local/geneos/licd

Selecting a port number Copied

Each installed licence daemon must have a unique port on which it listens for connections from other Geneos processes. The default port for the licence daemon is 7041. If this port is unavailable, you must select an available unique port.

Running multiple Licence Daemons Copied

You are not able to run more than one instance of the licence daemon on a single server. If you attempt to start a second licence daemon on the same box, it will exit with the log message “Another License daemon is already running on this host - terminating”.

An organisation should not require more than one licence daemon. Administrators can partition licences between departments using the licence grouping functionality (see Licence Groups).

Selecting the log file directory Copied

The Licence Daemon generates a log file. You can specify a particular location using the -log command line parameter (See Command Line Options). For more information regarding the Licence Daemon log file, see Licence Daemon log.

Required libraries Copied

RHEL 9 Copied

RHEL 8 Copied

Installing a Licence Daemon Copied

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

Extracting files Copied

The licence daemon package is supplied as a compressed tar file with a name in the format licd.<platform>.GA<version number>.tar.gz.

Extract this to your installation directory. The package contains the licence daemon binary.

Packages for certain operating systems may contain additional shared libraries inside a folder called compat. These may need to be put on the LD_LIBRARY_PATH when the licence daemon is run.

Installing the Licence File Copied

Before running up the licence daemon, you must place the licence file in the location that the licence daemon is run from. The licence file needs to be called geneos.lic. See The Licence File for further information on this file.

Executing Copied

The licence daemon binary is named:

licd.<platform>

The binary can be executed without any command line options, at which point it is ready to listen to and accept incoming connections from Geneos processes on the default port 7041.

You can now run Gateways so that they connect to this licence daemon. The Gateway must be given the hostname of the box that the licence daemon is running on as a command line option. For more information, see Gateway Licensing.

Copied

Command Line Options Copied

The following command line options are available in the licence daemon:

The Licence File Copied

The licence file contains information about the number of each type of Geneos feature that a particular client installation is allowed to use. The licence file must be called geneos.lic and must be placed in current directory of the licence daemon before it is started.

Acquiring a Licence File Copied

The licence file will be provided by ITRS. Request a license by contacting support ITRS support.

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 Copied

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 Copied

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 Copied

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.

Licence Groups Copied

Licence groups provide licence daemon administrators with a way to control the usage of Licences through out their estate. The licence daemon administrator can assign a number of licence tokens to a group and they assign one or more Gateways to that group. The group is assigned using the licencing group setting in the Operating Environment section in the GSE. When Gateways request licences from the licence daemon they provide the group in which they reside as part of their request. The licence daemon then tries to acquire the licence from the licences assigned to the group by the licence daemon administrator. If the licence daemon has allocated all the licences of the type requested that have been assigned to the group for which the request is made then there are no more licences available. If the licence daemon is running in ENFORCEMENT mode, the licence daemon rejects the licence request. If the licence daemon is running in MONITORING mode, then the licence is still be granted, but the number of allocated licences for the group will exceed the number assigned and the number available is reported as negative.

Any number of groups can be specified by the administrator. The system creates a final group called Other. Any request for a licence from a Gateway that is in a group that has not been configured by the licence daemon administrator is allocated from the Other group.

Example

ITRS provides a licence that give the licence daemon administrator 100 tokens for servers, cpu, and hardware, and unlimited for Gateways which specifies ENFORCEMENT mode. They can then split this into three groups G1, G2, and G3 as follows:

Starting with 3 Gateways running, all in group G1, and between them they have 40 Netprobes (all running cpu and hardware plugins).

If a 4th Gateway in group G1 with 20 Netprobes (all configured to run cpu and hardware plugins) is started then only 10 of those 20 probes would be granted a licence, despite the fact that there currently are 60 unused server, cpu and hardware licences. This is because this Gateway can only take licences assigned to Group G1.

If a 5th Gateway in group G4 with 50 Netprobes (all configured to run cpu and hardware plugins) is started then only 20 of those 30 probes would be granted a licence, despite the fact that there currently are 50 unused server, cpu and hardware licences. This is because this Gateway can only take licences assigned to Group Other. The Group Other has an assignment of unlimited gateways, 20 servers, 20 cpu plugins and 20 hardware plugins. This is because the licences assigned to Group Other are the licences assigned by ITRS less the licences assigned by each group.

Group Validation Copied

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 Copied

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 Copied

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.

GROUP G1
<gateway> = *
<servers> = 50
<cpu> = 50
<hardware> = 50

GROUP G2
<gateway> = *
<servers> = 20
<cpu> = 20
<hardware> = 20

GROUP G3
<gateway> = *
<servers> = 10
<cpu> = 10
<hardware> = 10

Licence Persistence Copied

Gateways continue to function if they lose connection to the licence daemon. Each successful licence request is cached by the Gateway so if the connection is lost, the Gateway continues using the cached licences. The cache is persistent across both Netprobe and Gateway restarts.

While the Gateway is disconnected from the licence daemon, it cannot acquire new licences. The following actions will fail to gain a licence until the Gateway re-establishes connection to the licence daemon:

• Changing Gateway name: If this occurs, the entire Gateway ceases to function until it can reconnect to the daemon. All monitoring will cease.
• Adding a new Netprobe: New Netprobes are not licenced even if they are on the same server as an existing probe.
• Changing port / host of a Netprobe.
• Adding a new sampler on a Netprobe: the new sampler will not be granted a licence. - If a new sampler of the same type as an existing sampler is added on the same Netprobe the cached licence is used. However, should the Netprobe/Gateway restart, it is undetermined which of the two sampler (the original or the new one) will be granted a licence.
• Add a new Gateway component: e.g. Compute Engine, Knowledge Base if not previously used in the setup.
• Add a Gateway breach predictor plugin. (All other Gateway plugins do not require any licence other than the Gateway licence to run).

Licence Daemon log Copied

The Licence Daemon generates a log file. See Selecting the log file directory and Command Line Options for information about where this file is written to.

Log file size Copied

By default, the maximum size of the log file is 10485760 bytes (or 10 MB). When the log file reaches 10 MB, the file is renamed by adding a .old extension and a new log file is opened.

The maximum size of the log file can be changed to a limit of 4,294,967,296 bytes (or 4 GB) by setting the environment variable MAX_LOG_FILE_SIZE_MB to an appropriate amount (in MB).

Archive the log file Copied

The environment variable LOG_ARCHIVE_SCRIPT can be set to call a UNIX script that can be used to archive the log files into an archive area.

The script is run after the log file has been renamed, and the script is passed the name of the .old file as a parameter.

By default the script is not called.

Log file entries Copied

On start up, the Licence Daemon writes a summary of its configuration so that the administrator can confirm that it is running as expected.

The log can contain three types of entries:

• Errors and warnings.
• Significant events.
• Licence rejections.

These entries are outlined below.

Errors and warnings Copied

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 Copied

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 Copied

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

Monitoring Copied

There are two separate plug-ins that can be used to monitor the licence daemon. These are the Gateway Data plug-in and the Licence Usage plug-in.

Gateway Data Copied

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.

Licence Usage View Copied

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 View Copied

Provides details of the licence status.

Overall Copied

Provides a summary of all the licence tokens that have been used.

Headline legend Copied

The headline cells above the table display the following data:

Table legend Copied

The table cells display the following data:

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 Copied

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.

Reporting Copied

Reporting is available via a web interface on the licence daemon. This can be accessed via http://<host>:<port>/licensing, 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. For more information about the command line options for serving the web interface and specifying the detail level of reports, see Command Line Options in Geneos Licence Daemon.

The web-front end shows the following reports:

Licences Report Copied

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:
4. 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 Copied

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.

Summary Copied

The summary CSV page contains the same information as the web page. The main difference is that the tables in the web page are merged into a single table (starting on row 6 of the page), so an extra column of Group is added.

Summary CSV example

samplingStatus  OK
expiry  12-May-24
mode    ENFORCING
licenceName     MyLICD
hostName     ITRSLP256
hostId     68bf4e0e
rejectedRequests        1
Group     Token     Total           Used    Used1DayMax    Used1WeekMax    Free    
Overall   cpu       Unlimited       1       1               1              Unlimited
Overall   disk      Unlimited       1       1               1              Unlimited
Overall   gateway   Unlimited       1       1               1              Unlimited
Overall   hardware  Unlimited       1       1               1              Unlimited
Overall   network   Unlimited       1       1               1              Unlimited
Overall   servers   Unlimited       1       1               1              Unlimited

Summary CSV raw data

samplingStatus,OK
expiry,12 May 2024
mode,ENFORCING
licenceName,MyLicd
rejectedRequests,1
hostName,ITRSLP256
hostId,68bf4e0e
Group,Token,Total,Used,Used1DayMax,Used1WeekMax,Free
Overall,cpu,Unlimited,1,1,1,Unlimited
Overall,disk,Unlimited,1,1,1,Unlimited
Overall,gateway,Unlimited,1,1,1,Unlimited
Overall,hardware,Unlimited,1,1,1,Unlimited
Overall,network,Unlimited,1,1,1,Unlimited
Overall,servers,Unlimited,1,1,1,Unlimited

Details Copied

The details view represents the list of requests that the licence daemon currently has accepted and are active. The Gateway only requests licences as they are required so if a probe is taken down, the Gateway releases the licences, they are removed from the summary count and they are removed from the details list.

Details CSV example

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

Details CSV raw data

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

When correlating the Details CSV report with the Licences Report or the Gateway Licence Usage View, it is useful to keep in mind that the count of the instances of use of a particular type of licence as shown in the CSV report will not necessarily be equal to the corresponding “Used” column in the Licences Report. For example, some plug-ins could be licensed by server.

i.e. Having one license for the TOP plugin would mean you can run an unlimited number of instances of that plug-in on a single servers. So the usage count in the Licences Report would be 1, but the number of rows in the Details CSV with accepted requests for the TOP plugin could be five. In this case, all five requests would have to originate from the same server.

The groups column in the two Summary and Details reports differ. In the Summary view the group column represents the preallocated group defined in the licence daemon configuration, while in the Details view it represents the licensing group specified in the gateway configuration. Thus in the above example the probe running on host2 is configured to be part of licensing group G2x. The Summary view reports the group as Other, indicating that group G2x is not configured with preallocated tokens in the licence daemon.