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.

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 = Test Report

CPU_DEFAULT_COUNT = 4

CPU_CORES_PER_UNIT = 2

PLUGIN_REPORT_MODE = INSTANCE   (or SERVER)

PENDING_TIMEOUT = 5

GENERATE_GW_CSV_REPORTS = TRUE

LOGIN = myUser myPassword

LOGIN = myUser ##system##

GATEWAY = testhost:4400 myUser myPassword
GATEWAY = testhost:4400
GATEWAY = testhost myUser myPassword
GATEWAY = testhost

SECURE_GATEWAY = testhost:4400 myUser myPassword
SECURE_GATEWAY = testhost:4400
SECURE_GATEWAY = testhost myUser myPassword
SECURE_GATEWAY = testhost

SECTION = PRODUCTION
GATEWAY = testhost:4400 myUser myPassword
GATEWAY = testhost:4400
SECTION = QA
GATEWAY = testhost:4401 myUser myPassword
GATEWAY = testhost:4401

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

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:

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.