Licence Auditor

Intended Audience Copied

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 Copied

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.

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 Copied

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 Copied

Once the Auditor has attempted to connect to all the configured gateways, it will output a number of CSV reports.

Configuration Copied

File format Copied

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 Copied

The following settings are available for use in the setup file.

LISTEN_PORT Copied

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 Copied

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 Copied

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 Copied

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 Copied

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 Copied

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 Copied

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 Copied

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 Copied

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 Copied

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 Copied

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 Copied

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

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 Copied

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 should be like this:

• For Internet Explorer, use http://audithost:auditport/.
• For Google Chrome or Microsoft Edge, use http://audithost:auditport/index.html.

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 Copied

The following image shows an example of the report generated by the license auditor.

Understanding the Audit HTML Reports Copied

Sections Copied

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
• SectionOne - Summary - Framework (CPU) - Plug-Ins - Details - Framework (CPU) - Plug-Ins
• 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 Copied

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 Copied

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:

Possible status values for hosts are:

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 Copied

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 Copied

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 Copied

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 Copied

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 Copied

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.