If you are currently using version 5.x.x, we advise you to upgrade to the latest version before the EOL date. You can find the latest documentation here.
Licence Auditor - User Guide
Intended Audience
This document is intended for general use. It is expected that users are familiar with the Geneos product and concepts prior to reading this document. ITRS Support staff may find this document more helpful than other readers, since this component allows them to automate a previously manual task.
Introduction
The Licensing Auditor assists users in gathering auditing data in an automated manner, rather than the time-consuming manual method used currently. This data will then be used to determine licensing requirements for the target system.
The Auditor operates by connecting to a set of configured gateways sequentially and receiving select monitoring information. This information is stored internally by the Auditor, and is used to generate reports of the current licensing state of the system. Reports can be generated by users connecting to the Auditor via a web browser and requesting the relevant page.
Note: If gateways are running with security settings, the auditor will require a user to login and receive data. Since auditor only needs to examine data VIEWONLY permissions for this user are sufficient.
Caution: 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.
Sequential Connections
The Auditor connects to the gateways in the order that they are listed in the setup file. Once audit data for a particular gateway is received, the auditor will disconnect from that gateway and connect to the next. Once all the gateways listed in the setup file have been attempted, the Auditor will show a message that it is now ready to report.
Gateways that the auditor failed to connect to will be ignored and connection will not be re-attempted. A list the gateways that it failed to connect to will be shown at the end.
If a gateway connection goes down while auditor is gathering audit data from that gateway, the Auditor will retain any information it had obtained so far. Similarly if a probe connected to the gateway being currently processed goes down, the Auditor will skip that probe and continue on. In this case it will still attempt to gather auditor data pertaining to the remaining probes.
Note: Auditor will attempt to connect to each gateway only once. Regardless of whether or not it successfully obtains all the required audit data, connection will not be attempted again. Hence it is necessary to ensure that all the relevant gateways and probes are up before running the auditor.
CSV Reports
Once the Auditor has attempted to connect to all the configured gateways, it will output a number of CSV reports.
Configuration
File format
Configuration for the auditor is specified in a
flat-format text file. By default auditor looks for a
file named auditor.setup
in the working
directory, but a different file may be specified using
the -setup
command-line option. The
setup file is read by the auditor at the beginning of
the audit run. Any updates to the setup file after
auditor has been started would be ignored.
Configuration settings are specified in the format
SETTING=VALUE
(with optional
white-space around the equals sign). A hash
(#
) character at the start of a line
symbolises that the line is a comment and should be
ignored.
Settings
The following settings are available for use in the setup file.
LISTEN_PORT
LISTEN_PORT = 8080
The auditor listen port can be specified in the
setup file, if it has not already been specified
using the ‑port
command-line option. This
port will be the port users connect to with their web
browsers to request a report. The default listen port
is 7048. If possible it is recommended that the
listen port be set to 80 (the default HTTP port)
however this typically requires the auditor to run
with root privileges.
REPORT_TITLE
REPORT_TITLE = Test Report
The report title appears at the top of every report. Users can use this setting to alter this title to their preferences. This setting defaults to an empty string.
CPU_DEFAULT_COUNT
CPU_DEFAULT_COUNT = 4
The CPU default count specifies how many CPU units the auditor should estimate, for a server for which there is no CPU data. This value will apply for servers where a Netprobe is configured in a gateway setup, but is not currently running, or for servers where a Netprobe is running but there is no CPU plug-in data. The default value is 4.
CPU_CORES_PER_UNIT
CPU_CORES_PER_UNIT = 2
The CPU cores-per-unit setting specifies how many logical CPU cores will be attributed to a single CPU license unit. For example, with this setting set to 2, an 8-core machine will consume 4 CPU license units. With this setting set to 4, the same 8-core machine will only consume 2 CPU license units.
PLUGIN_REPORT_MODE
PLUGIN_REPORT_MODE = INSTANCE (or SERVER)
The plug-in report mode specifies how plug-ins are
counted by the auditor, either per‑instance or
per‑server. These are configured by specifying
INSTANCE
(the default) or
SERVER
respectively.
In per-instance mode, two instances of the same plug-in running on the same server (either in the same Netprobe or separate Netprobes) will consume 2 licenses for that plug-in. In per-server mode, they will only consume a single license.
PENDING_TIMEOUT
PENDING_TIMEOUT = 5
This optional setting specifies (in minutes) the maximum time the auditor will wait for a particular gateway to return audit data before moving on to the next. The default value for this setting is 5 minutes.
When the Auditor processes a gateway it attempts
to obtain information from Hardware and CPU samplers
on each probe if these are configured. However, if
these samplers have not yet had a chance to sample
since the particular gateway and probe was stated,
the Auditor will wait until they do. However, based
on, for example the active times setting of those
samplers, it may be the case that they will not
sample again for an unacceptably long time. In these
cases based on the PENDING_TIMEOUT
specified the
Auditor will eventually give up and move on the next
gateway.
If any gateways were skipped in this manner the Auditor will give a warning at the end of the Audit run. This warning will list the number of gateways that had to be skipped.
This setting can also be passed to auditor using
the command line parameter -ptimeout
which will override the
setting if present in the set-up file.
GENERATE_GW_CSV_REPORTS
GENERATE_GW_CSV_REPORTS = TRUE
This optional setting specifies whether CSV reports will be written to disk for each gateway that the Auditor successfully connected to or just generate reports for each section and the overall summary.
LOGIN
LOGIN = myUser myPassword
The login setting specifies the login credentials
to use for all GATEWAY
settings declared under
this setting. The username should be the same as that
defined on the gateway and have at least VIEWONLY
permissions.
In order to use a system logon without a password, ##system## should be used.
LOGIN = myUser ##system##
GATEWAY
GATEWAY = testhost:4400 myUser myPassword
GATEWAY = testhost:4400
GATEWAY = testhost myUser myPassword
GATEWAY = testhost
The GATEWAY
setting specifies a
gateway for the auditor to connect to. The format of
this setting is the same as that for a legacy
ActiveConsole (ActiveConsole 1), and specifies the
hostname and the listen port of the gateway.
Therefore, gateway definitions can be copied and
pasted from the ActiveConsole set-up.
Following the gateway host, there are fields to
specify a username and password. If using the
LOGIN
setting described above,
these fields are then optional and will override the
LOGIN
credentials if specified.
Otherwise the fields are mandatory and are used when
connecting to that gateway.
Finally, the gateway port can be omitted when specifying the gateway. In this case, auditor will attempt to connect to the gateway host on the default gateway port of 7039.
SECURE_GATEWAY
SECURE_GATEWAY = testhost:4400 myUser myPassword
SECURE_GATEWAY = testhost:4400
SECURE_GATEWAY = testhost myUser myPassword
SECURE_GATEWAY = testhost
The SECURE_GATEWAY
setting specifies
is similar to the GATEWAY
setting. It also
specifies a gateway for the auditor to connect to.
The difference is that if the GATEWAY
setting is used, the
auditor will connect using an insecure TCP
connection. However, if the SECURE_GATEWAY
setting is used,
the auditor will connect using a secure SSL
connection.
The SECURE_GATEWAY
setting is
otherwise identical to the GATEWAY
setting. The gateway port
is optional as are the username and password.
SECTIONS
SECTION = PRODUCTION
GATEWAY = testhost:4400 myUser myPassword
GATEWAY = testhost:4400
SECTION = QA
GATEWAY = testhost:4401 myUser myPassword
GATEWAY = testhost:4401
Users can use this setting if they have a large number of gateways connected to the license daemon and want to organise the audit report into logical groupings.
SAMPLE SET-UP
# Auditor Configuration File
# Specify the Auditor listen port below
LISTEN_PORT = 8080
# The report title is placed as the title of each report page
REPORT_TITLE = ITRS America Inc.
# Gateway login (in the form of <username> <password>)
LOGIN = jtiu ##system##
# Specify individual gateways below. Specification takes the form of
# GATEWAY=<gateway> <user> <password>
# or if the LOGIN is specified above
# GATEWAY=<gateway>
SECTION = PRODUCTION
GATEWAY = 192.168.2.1:4400
SECTION = QA
GATEWAY = 192.168.10.2:5401
Obtaining a report
Once the Auditor has attempted to connect to all the gateways, reports can be generated. Two types of report are available: HTML and CSV.
HTML Reports
The auditor will start listening on the configured port for HTTP connections. To obtain a report, the user must connect to the auditor using a web browser. The URL would then be: http://audithost:auditport/
For example if the auditor were running on "myhost" with a listen port of 8080 the URL would be:
http://myhost:8080/
If the auditor is configured to use the HTTP listen port of 80, then there is no need to include the port in the URL. In this case, users could just type:
http://myhost/
Example HTML report
The following image shows an example of the report generated by the license auditor.
Understanding the Audit HTML Reports
Sections
The audit report is split up into several sections, which display the audit data at a different level of granularity. The basic structure of a report consists of an overview, followed by a section breakdown for each section configured in the auditor configuration. This structure can be seen below:
- Overview
- Summary
- Cpu
- Plug-Ins
- Details
- Cpu
- Plugins
- Summary
- SectionOne
- Summary
- Framework (CPU)
- Plug-Ins
- Details
- Framework (CPU)
- Plug-Ins
- Summary
- SectionTwo
- …
- SectionX…
The overview summary section displays the overall totals for all audited components. In this section, the CPU and Plug-In details are given broken-down by section and a total figure.
The overview details section displays additional details of the summary data. In the case of both CPU and Plug-Ins, these details explain the duplicate adjustments that were made to the totals. These adjustments are to avoid counting CPUs or plug-ins multiple times, for hosts which are shared between different audit sections.
Each section (a set of gateways, as configured in the auditor setup file) is then described in its own section of the report. A section summary contains details of CPUs and plug-ins, showing the usage for each gateway in the section and the section total.
The section details region of the report explains how the figures in the section summary were derived. For both CPU and plug-ins, a table is displayed for each gateway showing the hosts (or plug-in instances) which are contributing to the total counts for that gateway. An additional table is also shown for the duplicate adjustments, to eliminate any duplicate counts for hosts that are common to gateways in that section.
Duplicate adjustments
Duplicate adjustments are performed for CPU Unit counts, and for plug-in counts if auditor is running in per‑server plug-in licensing mode. The purpose of these adjustments is to disregard duplicate counts, which arise when the same server is monitored by multiple gateways, and potentially across different sections (e.g. departments).
Auditor uses two metrics to identify servers; the resolved IP address of the Netprobe host, and the hostid data (if available). On Windows, the MAC address of the first network interface is used as the hostid, since Windows does not natively support this feature unlike Unix OSes.
Connected status
The connected status field appears both in the section summary, and the section detail tables. The section summary table shows whether the auditor is connected to this gateway or not. The section details table (see example below) shows whether the auditor is connected to a particular host, for a given gateway.
Possible status values for gateways are:
Value | Description |
---|---|
Connected | The gateway is currently connected auditor. |
Disconnected | The gateway is not currently connected auditor. |
Possible status values for hosts are:
Value | Description |
---|---|
Connected | The host is currently connected to this gateway. |
Disconnected (local) | The host is currently not connected to this gateway, but the audit data is current since the host is connected to another audited gateway. |
Disconnected | The host is not currently connected to any audited gateways. |
In the following example, we are looking at the hosts configured for the gateway "Audit Example". You may notice that the values for CPU units in this example have two tags after them, "(dis)" and "(est)", which stand for "disconnected" and "estimated" respectively.
The disconnected flag will appear, if a host that was previously seen and audited, is then disconnected from auditor. In this case auditor will display the last known data for this host (in this case, 1 CPU unit), but will flag this since the data is not current.
The estimated flag will appear if a host has never been seen by auditor. In this case, auditor will estimate the number of CPU units for this host. To produce accurate figures, users are recommended to ensure the Netprobes on these hosts are running and that the CPU sampler is present.
CSV Reports
Once the Auditor has attempted to connect to all the configured gateways, it will write out CSV reports of the infrastructure it has inspected. There will be three types of reports written:
Gateway Reports
These reports show information about the utilisation of a single gateway.
Each row of the report corresponds to a "host" on which netprobes are run. The probe instances column allows you determine how many netprobes were on that host connected to the gateway. There are also additional rows for Duplicate Count Adjustment when plugins are licensed per server and an overall totals row.
If the Gateway has Gateway plug-ins configured, an additional row for all the Virtual Probes on the Gateway will also be present, with the totals for the instances of the Gateway plug-ins.
The report has the following columns:
-
- Section Name
- Name of the section this gateway falls under in the Auditor configuration
-
- Gateway
- Name of the gateway
-
- Date
- The date the audit was run
-
- Netprobe Hostname
- The hostname of this host
-
- IP Address
- The IP address of this host
-
- HostID
- The unix host id of this host. On Windows this will be the MAC address of the machine
-
- Connection Status
- Whether the gateway has connected to at least one of the probes configured on this host
-
- Managed Entities
- The number of Managed Entities running on this host
-
- Physical CPUs/Sockets
- The number of Physical CPUs on this host
-
- Logical CPUs/Cores
- The number of logical processors on this host
-
- CPU Units
- The number of chargeable CPU Units on this host See the CPU_CORES_PER_UNIT setting
-
- Probe Instances
- The number of netprobes connected to this gateway running on this host
Additional columns then follow for the total number of instances of each plugin across all the netprobes running on this host. The Duplicate Count Adjustment row then lists the adjustment for these plugin totals if licensing per server.
The CSV reports are generated in the auditor working directory and follow the naming convention:
<AUDIT_TITLE>_<GATEWAY_NAME>.csv
Section Reports
These reports show information about utilisation across all the gateways defined in a section in the Auditor configuration file. The columns are the same as the gateway reports.
Each report consists of all the individual gateway reports for all the gateways in the section listed one after the other with additional rows. The section Duplicate Count Adjustment shows the adjustment for the CPU and Plugin information where probes are run on the same host but are connected to different gateways in the same section.
There is an additional row for the Grand Total across the entire section.
The CSV reports are again generated in the auditor working directory and follow the naming convention:
<AUDIT_TITLE>_<SECTION_NAME>.csv
Summary Reports
The final report shows a summary of usage across all the gateways and sections in the Auditor configuration. There is a row for each section as well as rows for Duplicate Count Adjustment and the overall total.
The report has the following columns:
- Section Name — Name of this section in the Auditor configuration
- Date — The date this audit was run
- Netprobes — The total number of netprobes configured across all the gateways in the section. This column is the same as the total of the Probe Instances column in the section report
- Managed Entities — The total number of Managed Entities configured across all the gateways in the section This column is the same as the total of the Managed Entities column in the section report
- Physical CPUs/Sockets — The total number of Physical CPUs across all the hosts running probes that are connected to gateways in this section
- Logical CPUs/Cores — The total number of logical processors across all the hosts running probes that are connected to gateways in this section
- CPU Unit — The total number of chargeable CPU Units across all the hosts running probes that are connected to gateways in this section
Additional columns then follow for the totals for each plugin configured on probes that are connected to gateways in the section.
The Duplicate Count Adjustment shows the correction taken into account for hosts that run netprobes that are connected to gateways in different sections of the auditor configuration.
The CSV reports are again generated in the auditor working directory and follow the naming convention:
<AUDIT_TITLE>_Summary.csv
Debugging
Certain debugging flags can be passed to auditor to
get verbose information output the log file. Pass the
flag -debug as a command line argument or set the
environment variable DEBUG =Auditor:debug
to achieve the same.
This will help to get extra information about the
Auditor's activities when it connects to and gathers
audit data from gateways.