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.
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 plug-ins.
The Licence Daemon is a Geneos process that other Geneos processes connect to in order to acquire permissions to use certain Geneos features. Currently, the Gateway is the only processes that connects to the licence daemon.
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.
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.
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.
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).
Please refer to the Geneos Compatibility Matrix for the list of supported platforms.
Select a directory to install and extract the files. For new installations the following directory is recommended:
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.
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).
This section describes how to install a licence daemon and run it so that Geneos processes can connect to it and request licenses.
The licence daemon package is supplied as a compressed tar file with a name in
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
compat. These may need to be put on the
LD_LIBRARY_PATH when the licence daemon is run.
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
The licence daemon binary is named:
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.
The following command line options are available in the licence daemon:
Displays help about the topic if specified, or this help message. Topic can be any of the parameters shown below.
Used to display version information for the licence daemon. It contains information about the exact version of the licence daemon and all the libraries contained within. This information is often useful when raising a support issue.
Used to specify the port the licence daemon listens on for other Geneos processes to connect to. The option must be followed by the listen port, a positive integer in the range 1-65535 inclusive.
Note: On some systems ports in the range 1-1024 are reserved and the licence daemon will need special permissions to listen on a port in this range.
If -port is not specified, the default port of 7041 is used.
Used to specify the name of the Licence Daemon logfile.
If neither of these are the set, the log is printed to stdout.
Running the Gateway with the -nolog option overrides all other log settings and prints output to stdout.
For more information about the logfile, see Licence Daemon Log.
Specifies the directory in which the administrator will place the grouping allocations. Each group will have a single file specifying the tokens that have been allocated to that specific group.
See Licence Groups.
Allows the administrator to generate a template for group allocation files.
See Licence Groups.
||Allows the administrator to tell the licence daemon not to check that the number of preallocated tokens in group files are less than or equal to the number of tokens in the licence file. This option is only available if the licence daemon is running in MONITORING mode.|
These flags allow the Licence Daemon to be configured to listen on a secure port, rather than an insecure port. The Licence Daemon only listens for licence requests on a single port, so it is either listening just on an insecure port or just on a secure port.
For more details, see Secure Communications.
Specifies the minimum TLS version. The accepted values are:
For more details, see Secure Communications.
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
geneos.lic and must be placed in current
directory of the licence daemon before it is started.
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.
To change the licence file:
- 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.
- Overwrite the current
geneos.licwith its replacement.
- 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.
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.
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 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.
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:
|Group G1 file||
|Group G2 file||
|Group G3 file||
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.
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
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
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.
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
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
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 exiting sampler is added on the same Netprobe, it's licence request as it does not exist in the cache. However, should the Netprobe/Gateway restart, it is undermined 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).
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
.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
MAX_LOG_FILE_SIZE_MB to an appropriate amount (in MB).
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
By default the script is not called.
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.
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.
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.
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
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.
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
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 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)
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.
An include file with example rules is available here.
Reporting is available via a web interface on the
licence daemon. This can be accessed via
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.
The web-front end shows the following reports:
The licences report shows the following information:
- 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).
- Expiry date of the current licence file.
- A table showing information
related to each type of licence found in the
- Licence — Name for the particular type of licence. For example, the licence that allows you to run CPU plug-ins is called "cpu".
- 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.
- Used — Number of licences that are currently being used.
- Free — Number of unused licences.
- 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.
The Report web page provides two links that return CSV reports. These are:
- Summary —
- Details —
host is the host on which the daemon is
port is 7041 unless it has been manually
specified on the licence daemon command line.
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 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
Summary CSV raw data
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
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.