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 will send a licence request to the licence daemon. This request will be 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 section 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 section 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 will need to select an available unique port.
You will not be 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".
You may, however, run a licence daemon on the same box as a legacy licence daemon. This is the previous incarnation of the licence daemon which performs licensing for gateway1's.
It is not expected that more than one licence daemon is needed. Administrators can partition licences between departments using the licence grouping functionality (See Licence Groups).
The Licence Daemon generates a log file. The daemon log can been written to a particular location via the -log command line parameter (See Command Line Options in the Running the Licence Daemon). For more information regarding the Licence Daemon log file, seeLicence Daemon log.
This section will describe 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 simple to install. The package is supplied as a compressed tar file with a name in the format:
Extract this to your installation directory. The package will contain licence daemon binary.
In the case of certain operating systems it may contain additional shared libraries inside a folder called 'compat' which may need to be put on the LD_LIBRARY_PATH when the licence daemon is run.
Before running up the licence daemon, you will need to 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.
The licence daemon binary will be named:
The binary can be executed without any command line options, at which point it will be 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 would need to be given the hostname of the box that the licence daemon is running on as a command line option. More information on this can be found in the Gateway2 Reference Guide.
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 called '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 will need to be provided with the hostid and hostname of the server upon which 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.
Procedure for changing the licence file:
Shut down the licence daemon.
This will 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. Please 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.lic' with 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 section Reporting). The Overall table will show a list of the number of each licence tokens provided by ITRS and the top right will show 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 will 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. Please see section 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 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 will then try to acquire the licence from the licences assign 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 will reject the licence request. If the licence daemon is running in MONITORING mode then the licence will still be granted, but the number of allocated licences for the group will exceed the number assigned and the number available will be reported as negative.
Any number of groups can be specified by the administrator. The system will create 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 will be 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 G1 <gateway> = * <servers> = 50 <cpu> = 50 <hardware> = 50
Group G2 file
GROUP G2 <gateway> = * <servers> = 20 <cpu> = 20 <hardware> = 20
Group G3 file
GROUP G3 <gateway> = * <servers> = 10 <cpu> = 10 <hardware> = 10
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 again 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 again 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 reason 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. In order 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 to may licences in their group files then 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 is is clear when a department is over using resources. There is a command line option called -ignore-group-size-check that will allow 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).
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.
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 in the Running Licence Daemon section). 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, 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. In order 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 in the Running Licence Daemon section) will create a file containing all the tokens specified in the licence file. An example is shown below. 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.
Group Template file generated by the licence daemon
GROUP [enter group name here] <gateway> = ? # of * <servers> = ? # of 100 <cpu> = ? # of 100 <hardware> = ? # of 100
In order 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 in the Running Licence Daemon section). This will allow 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.
Gateways will 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 probe and gateway restarts.
While the gateway is disconnected from the licence daemon it cannot acquire new licences. This means that 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 will cease to function until it can reconnect to the daemon. All monitoring will cease.
- Adding a new probe: New probes will not be licenced even if they are on the same server as an existing probe.
- Changing port / host of a probe
- Adding a new sampler on a probe: 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 probe it's licence request as it does not exist in the cache. However should the probe/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. (Currently all other gateway plugin 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 environment variable 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 will contain 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 D aemon.
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
The gateway provides two separate plug-ins that can be used to monitor the licence daemon. These are the Gateway plug-in and the Licence Usage plug-in.
The Gateway view 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: This contains the expiry dateof the licence provided by ITRS.
- licenseDaysRemaining: This contains the number of days remaining on the licence.
- licensingMethod: This 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 2 views if it connects to a licence daemon with no groups configured.
- LicenceUsage: This provides details of the licence status
- Overall: This 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 will not be created. However if the licence daemon is stopped after the gateway has started the Overall view will be maintained. The value of connected will be set to NO and the lastUpdateFromLICD will stop being updated.
If groups are configured (see Licence Groups), then more information is available. By default, the plugin will show a view for the gateway licensing group isntead of the Overall view. If any additional licensing groups are configured on individual probes, the appropriate group view will also be shown. If any of these the groups has not been configured on the licence daemon, the view for the Other group will be shown instead. (Only one Other view will be 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 will not be shown, only those configured. Any views explicitly configured for groups that do not exist on the daemon will result in an empty view with an error in the samplingStatus.
By default the plugin will show 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 will request views for G1, G2 and G3. The licence daemon will interpret the requests and views for managed groups that it requests and return the Other view for any non managed groups. Thus if the gateway requests G1, G2 and G3 but the licence daemon administrator has only configured G1 on the licence daemon, the views that will be 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 LicenceUsage or GatewayData plugins
- Set Critical severity if the gateway cannot connect to the licence daemon: Target licensingMethod in GatewayData or connected in the LicenceUsage plugin.
- Ensure that port, hostname and licence name are as expected: Target the respective cells in the LicenceUsage plugin
- Ensure licence daemon mode is as expected: Target the mode headlines in any of the LicenceUsage 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 LicenceUsage 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 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.
The web-front end shows the following reports:
The licences report shows the following information:
Name of the current licence file (this is 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 file.
- Licence: The name for the particular type of licence. For example, the licence that allows you to run CPU plug-ins is called "cpu".
- Total: The 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: The number of licences that are currently being used.
- Free: The number of unused licences.
- There are no more licences of this type: Amber
- More licences have been allocated than are specified in the licence file/group allocation: Red
- The licence daemon is in Enforcement mode: Green
- The licence daemon is in Monitoring mode: Amber
- The licence has expired: Red
If the licence daemon has not be configured to preallocate licence tokens to groups then 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. Please see Licence Groups for more information about licencing.
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.
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.