2.5. Subscription Asset Manager: Satellite 5.6 Usage Reports

Red Hat Satellite 5.6 has a utility (spacewalk-reports) to export information on the system inventory, organizations and associated subscritions, errata, and users.
Subscription management establishes relationships between systems, organizations, and subscriptions. The types of relationships, and the ways those relationships are described, are slightly different in Satellite when compared to the new subscription services at Red Hat. (This is described more in the Subscriptions Concepts and Workflows document.) The new subscription services create a direct relationship between a subscription and the system to which it is applied. In Satellite 5.x, the concept of channels meant that a system was granted access to a content stream and the overall subscription allowed a certain number of systems to have access — but there was no direct association between a subscription and a system.
Satellite enhanced reporting allows Satellite 5.6 servers to sync their system, subscription, and channel data over to a Subscription Asset Manager server. That Subscription Asset Manager server can then take the underlying subscription information and generate a report using Red Hat Subscription Management rules, revealing the relationships between systems and subscriptions in Satellite.
This gives Satellite administrators a greater level of detail and control over the systems in their Satellite inventory.

2.5.1. About Satellite Consolidated Reports

2.5.1.1. The Advantages of Enhanced Reporting
Subscriptions are frequently predicated on attributes of the underlying physical system, such as socket count, RAM, CPU, and cores. For virtual systems, subscriptions can be based on the host/guest relationship and inherited or restricted. Subscriptions can also be related to other products installed on the system.
The reporting in Satellite is more limited; it measures the overall counts of systems and subscriptions, but it does not associate subscriptions and systems or identify required subscriptions based on system attributes.
The enhanced reporting provides more detailed reports in two ways:
  • Determining actual subscription usage based on system attributes, host/guest relationships, and installed products.
  • Tracking historical subcription usage based on subscription statuses at different points in time.

Important

The enhanced reporting in Subscription Asset Manager only displays data about the Satellite 5.6 systems and organizations. It does not alter, update, or manage any systems, subscription assignments, or organizations in Satellite.
Both system management and subscription management for Satellite 5.6 must be performed in Satellite.
Like the Satellite reports, all of the Subscription Asset Manager report data can be exported to a CSV, so any additional data analysis can be performed. Additionally, a Subscription Asset Manager report can be exported to a JSON file and can be rendered visually in the Subscription Asset Manager UI (including system-level details) so it can be quickly read and interpreted.
2.5.1.2. Differences in Subscription Statuses from Satellite
Because enhanced reporting uses a different set of criteria — system attributes instead of channel access — to calculate the required subscriptions for a system, there are potentially differences between how enhanced reporting reports subscription status for a system and how the same information is reported in Satellite.
For example, many Red Hat Enterprise Linux subscriptions are for two sockets. A four-socket system, then, requires two subscriptions to cover all its socket pairs. If only one subscription is attached to that system, then the Subscription Asset Manager report shows that system as having an insufficient status. However, in Satellite, the same system only consumes a single channel entitlement, regardless of the number of sockets.
Additionally, Satellite has two different types of subscriptions: system entitlements (which are required to register a system) and software channel entitlements (which is what actually provides access to content, updates, and support). In the new subscription structure (and, thus, in Subscription Asset Manager), the system and channel entitlements are merged into a single product subscription which most closely correlates to channel entitlements.
Lastly, Satellite allows channels to be cloned. If a system is registered with a cloned channel, then no channel entitlements are used, so no entitlements are decremented from the available entitlements pool. However, when the channel information is synchronized, the cloned channel is associated with its original Red Hat channel, and subscriptions are then properly attached to the system (or its status is shown to be invalid or insufficient).
2.5.1.3. Syncing Data from Satellite 5.6 to Subscription Asset Manager
A script is run periodically to sync data from the Satellite 5.6 server to the Subscription Asset Manager database, so the data are accessible for Subscription Asset Manager reports. Only certain Satellite informtion is synced:
  • System information (called system facts in Subscription Asset Manager) including the hostname, socket count, any host/guest relationships, and other relevant attributes
  • Satellite organizations and associated subscriptions
  • User information, including roles and administrator accounts such as Satellite Administrator and Organization Administrator
  • Satellite cloned channels and their associated, originating channel.
Synchronization occurs in two phases. First, the inventory information is pulled out of Satellite as a spacewalk-reports report, using the spacewalk-splice-checkin process. The information then is sent to the Subscription Asset Manager server. This synchronization step is run every four hours, by default.
Satellite 5.6 to Subscription Asset Manager Sync

Figure 25. Satellite 5.6 to Subscription Asset Manager Sync

From there, the information is collected from Subscription Asset Manager and sent to a dedicated backend database (separate from the normal Subscription Asset Manager database) and stored in the separate reporting server. This step is performed every ten minutes.
Subscription Asset Manager to Reporting Server Sync

Figure 26. Subscription Asset Manager to Reporting Server Sync

After the second phase of synchronization, once the data are stored in the reporting database, then enhanced reports can be run, using the populated system data.
2.5.1.4. Users in Satellite 5.6 and Subscription Asset Manager
As mentioned in Section 2.5.1.3, “Syncing Data from Satellite 5.6 to Subscription Asset Manager”, Satellite are synced over to Subscription Asset Manager and added as Subscription Asset Manager users. All of their organization and role assignments are preserved.
Satellite 5.6 passwords are not synced over to Subscription Asset Manager. Satellite users must log in with their Satellite username and a default password of CHANGEME.

Note

Satellite users are added to Subscription Asset Manager if they are added to the Satellite server, but they are not deleted in Subscription Asset Manager if they are deleted on the Satellite server. If a Satellite user is deleted, then that account must be manually deleted on the Subscription Asset Manager side.

2.5.2. Prerequisites

When using enhanced reporting, there are some additional system requirements:
  • A dedicated Subscription Asset Manager instance specifically for Satellite reporting.

    Warning

    A Subscription Asset Manager instance used for enhanced reporting can only be used as a reporting server for Satellite. It cannot be used as a regular Subscription Asset Manager instance to manage systems or data could be lost.
  • The crond service must be running.
  • An additional 4 GB of disk space must be available for the reporting database journal.
  • Additional packages for the reporting server
    • splice
    • ruby193-rubygem-splice_reports
    • spacewalk-splice-tool

2.5.3. Configuring Reporting

  1. Install Subscription Asset Manager, including the additional packages.
    1. Register the host system. Use the --autoattach option to attach the required subscriptions for the operating system immediately. 
      [root@server ~]# subscription-manager register --autoattach
Username: jsmith@example.com
Password:
    2. Wait several minutes for the updated content repositories to be added to the system configuration.
    3. Enable the [rhel-6-server-sam-rpms] repository. 
      [root@server ~]# yum-config-manager --enable rhel-6-server-sam-rpms
Loaded plugins: product-id, refresh-packagekit
========================= repo: rhel-6-server-sam-rpms =========================
[rhel-6-server-sam-rpms]
bandwidth = 0
base_persistdir = /var/lib/yum/repos/x86_64/6Server
baseurl = https://cdn.redhat.com/content/dist/rhel/server/6/6Server/x86_64/subscription-asset-manager/1/os
cache = 0
cachedir = /var/cache/yum/x86_64/6Server/rhel-6-server-sam-rpms
cost = 1000
enabled = 1
enablegroups = True
exclude =
failovermethod = priority
...
    4. Install the katello-headpin-all package using yum install: 
      [root@server ~]# yum install -y katello-headpin-all splice ruby193-rubygem-splice_reports spacewalk-splice-tool
    This can also be done when installing from an ISO image by using the --enhanced_reporting option. 
    [root@server cdrom]# ./install_packages --enhanced_reporting
  2. The reporting database is a MongoDB database. Set up the Mongo service on the system to start automatically, and then start the service. 
    [root@sam-server ~]# chkconfig mongod on 
[root@sam-server ~]# service mongod start
  3. Run the configuration script to set up the Subscription Asset Manager server, the default admin user, and the initial organization. 
    [root@server ~]# katello-configure --deployment=sam --org=Example_Org --user-name=samadmin --user-pass=secret
    The Subscription Asset Manager admin user is not the same as the Satellite 5.6 admin user.
  4. Still on the Subscription Asset Manager machine, create an SSH key to use to authenticate to the Satellite 5.6 machine. 
    [root@sam-server ~]# su - splice -s /bin/sh -c 'ssh-keygen -t rsa -f /var/lib/splice/id_rsa-sat -N ""'

Generating public/private rsa key pair.
Your identification has been saved in /var/lib/splice/id_rsa-sat.
Your public key has been saved in /var/lib/splice/id_rsa-sat.pub.
The key fingerprint is:
78:fa:c9:68:71:a2:a7:c1:ec:35:e3:43:ce:27:b7:d8 splice@dhcp129-162.rdu.redhat.com

The key's randomart image is:
+--[ RSA 1024]----+
|                 |
|                 |
|                 |
|       .         |
|      . S        |
|   o  +o.        |
|    +==+         |
|   ..+BOo.       |
|    o++=E.       |
+-----------------+
  5. Switch to the Satellite 5.6 machine.
  6. Create a new user which can run the required Satellite reports to sent to the Subscription Asset Manager server. 
    [root@sat-server ~]# useradd swreport
  7. Add the key file that was created on the Subscription Asset Manager machine to the authorized_keys file for the swreport user on the Satellite 5.6 machine. Include the command= option to restrict the swreport user to only running Satellite reports on the system. 
    [root@sat-server ~]# vim /home/swreport/.ssh/authorized_keys
	
command="/usr/bin/spacewalk-report $SSH_ORIGINAL_COMMAND" \
	ssh-rsa key_hash swreport@sat-server
    The command directive should be all on one line in the keys file.
  8. Set the proper permissions on the .ssh directory and the authorized_keys file: 
    [root@sat-server ~]# chown -R swreport:swreport /home/swreport/.ssh
[root@sat-server ~]# chmod 700 /home/swreport/.ssh
[root@sat-server ~]# chmod 600 /home/swreport/.ssh/authorized_keys
  9. Add the swreports user to the apache system group so that it can connect to the database. 
    [root@sat-server ~]# gpasswd -a swreport apache
  10. Switch back to the Subscription Asset Manager machine.
  11. Switch to the reporting service user (splice), and test that the user can SSH into the Satellite machine using the swreport key. 
    [root@sam-server ~]# su - splice -s /bin/bash
[splice@sam-server ~]$ ssh -i /var/lib/splice/id_rsa-sat swreport@sat-server.example.com splice-export
    Accept the key fingerprint if prompted.
  12. Edit the reporting configuration to recognize the Satellite 5.6 server. 
    [root@sam-server ~]# vim /etc/splice/checkin.conf

[spacewalk]
host=sat-server.example.com
ssh_key_path=/var/lib/splice/id_rsa-sat
login=swreport
  13. Edit the reporting configuration to use the Subscription Asset Manager administrator password that was set during the Subscription Asset Manager setup. 
    admin-pass=secret
  14. On the Subscription Asset Manager server, run the sync utility to populate the Subscription Asset Manager database with the Satellite 5.6 data. 
    [root@sam-server ~]# su - splice -s /bin/bash
[splice@sam-server ~]$ spacewalk-splice-checkin

    Note

    This can a long time to run on the initial sync operation.
    To improve the tool performance, set the number of threads for the spacewalk-splice-tool process to use. This should be one thread for every two cores on a low-utilization system or one thread for every three cores on a high-utilization system.
    For example: 
    [root@sam-server]# /etc/splice/checkin.conf

num-threads=3
  15. Get the Satellite 5.6 manifest from the Customer Portal.
    1. Log into the Customer Portal.
    2. Expand the Subscriptions tab, and select the Subscription Management > Subscription Management Applications item.
    3. Open the Satellite tab.
    4. If the Portal entry does not already exist, create the Satellite 5.6 entry and attach the required subscriptions.
      1. In the Satellite tab, click the Register a Satellite link.
      2. Fill in the required information for the Satellite 5.6 instance:
        • The name for the Satellite server entry.
        • The version of the Satellite instance; this should be 5.6.
      3. Click the Register button.
      4. In the Satellite 5.6 server's Subscriptions tab, select the subscriptions to add in the Available Subscriptions area.
        Be sure to set the appropriate quantity of subscriptions for each product selected. The quantity is the total number of subscriptions of that type available to the child organization.
      5. Scroll down, and click the Attach at the bottom of the window.
        Attaching subscriptions automatically updates the child organization's manifest.
    5. In the Satellite 5.6 server's entry page, click the Download manifest button, and save the archive file.
  16. Log into the Subscription Asset Manager UI (https://sam-hostname/sam) as a Satellite administrator, and switch to the appropriate Satellite 5.6 organization.
  17. Open the Subscriptions > Subscriptions tab, and click the Import Manifest link.
  18. In the middle of the import tab, click browse to navigate to the saved manifest file.
  19. Click the Upload button.

2.5.4. Running Reports and Getting Results

There is a default report configured which returns information for every organization and every system in every state that is being managed by Subscription Asset Manager.
It is possible to create additional report filters that return specific subsets of information or information for a given period of time. These custom reports are very useful for analyzing usage and compliance trends.
There is a lot more flexibility possible with the report form, however. In particular, there are three versatile settings:
  • The organizations to check for the report
  • The subscription statuses to include
  • The date range to check; this looks for systems which had the status within the given range, which may not necessarily be the current status for the system

Note

The data within the Subscription Asset Manager database includes historic subscription statuses. This allows reports to be generated to track subscriptions at a given point in time, not just the current date.
For example, if purchasing occurs in July, then a report can be configured to search for insufficient or invalid systems from April through June, to influence purchasing decisions.
The time filter also allows very short windows of time — the previous 24 or 48 hours — to be able to identify and remediate suscription issues immediately.
2.5.4.1. Creating Report Filters
  1. Click the Reports item in the administration menu.
  2. In the left column, click the New Filter link.
  3. Fill in the required information for the report, including the organizations, statuses, date range, and active states.
  4. Click the Save Filter button.
2.5.4.2. Running Reports
  1. Click the Reports item in the administration menu.
  2. In the left column, click the name of the report filter to run.
  3. Scroll to the bottom of the report page, and click the Run Report button.
    Alternatively, the report results can be exported to a CSV file. To export the data, click the Export Report button.
    The data are exported to a CSV file and, optionally, a JSON file which contains the system details. These files are contained in a ZIP archive named report-YEAR-MONTH-DAY-TIMESTAMPZ.zip.

    Note

    Selecting the Encrypt export checkbox means that the exported CSV and JSON files are encrypted and can only be accessed by a private key used by Red Hat support.
2.5.4.3. Subscription Asset Manager Reports Results and Data
The Subscription Asset Manager report returns a chart of all registered systems for all selected organizations, similar to the Dashboard.
The Reports Results

Figure 27. The Reports Results

There is also a list of all included systems. The list itself contains summary information such as the Subscription Asset Manager or Satellite server to which the system is registered, its status, its organization, and its most recent checkin time.
Clicking the name of any system pulls up more details subscription data for the system. The details page includes a history of subscription status changes for the given report period, the list of installed products and subscription information for each, and system facts (attributes about the physical machine and operating system, such as CPU, socket count, RAM, and cores).
The Reports Results: System Details

Figure 28. The Reports Results: System Details

Note

Only the last 250 check-ins are shown on the system's details page when viewing the enhanced report in the Subscription Asset Manager UI.
When the report results are exported, the same information is included in the export files.
The CSV report contains the summary information in the initial reports page: organization, registered subscription server, hostname, and subscription state, among others. 
_id, record, CHECK-IN TIME, STATUS, DB ID, SATELLITE SERVER, HOSTNAME, ORGANIZATION, LIFECYCLE STATE, 
{"ident"=>"072c8bdd-ca00-43d4-a000-0887c75b90c8"}, 522e0970af5d242094000002, 2013-09-09T14:23:27Z, "Current", "072c8bdd-ca00-43d4-a000-0887c75b90c8", "sam-server.example.com", "server.example.com", "ACME_Corporation", "Active",
The (optional) JSON file contains the same summary information, as well as the complete list of system facts and product information that is available on the details page. 
[{"_id":{"$oid":"522e0970af5d242094000002"},"_types":["MarketingProductUsage"],"instance_identifier":"072c8bdd-ca00-43d4-a000-0887c75b90c8","updated":"2013-09-09T17:46:24Z","splice_server":"sam13-dlackey-demo","name":"server.example.com","facts":{"memory_dot_memtotal":"3780964", ...

2.5.5. Troubleshooting Enhanced Reports

2.5.5.1. Enhanced Reporting Logs
Reporting Log Sizes

By default, enhanced reporting takes up to 200 MB of additional log space on a system. Logs grow at roughly 750 KB per system per month.

If the logging level needs to be changed, it can be edited in the log configuration file in /etc/splice/logging/basic.cfg.
Sync Log

All of the errors, messages, and operations for the sync tool are recorded in a specific tool log at /var/log/splice/spacewalk_splice_tool.log

2.5.5.2. Common Problems
Q: Why are no systems displayed in the report?
Q: Why are all systems marked as invalid?
Q: I updated subscriptions for a system or my Satellite server in Subscription Asset Manager, but those changes are not being reflected in the report.
Q: The link to the Satellite 5.6 UI in the report results is returning an HTTP 404 error.
Q:
Why are no systems displayed in the report?
A:
First, make sure that there are systems which match the given report filters.
If the filters should return some systems and there are still no systems displayed, this means that the information is not being pulled into the reporting database. There are several potential points of failure:
  • The information isn't being pulled from the Satellite server.
  • The information is not being properly transmitted from Subscription Asset Manager into the reporting database.
  • The information is not being properly stored in the database.
  • The information stored in Subscription Asset Manager is outdated.
First, make sure that the sync script is running by checking the history in the sync tool log, /var/log/splice/spacewalk_splice_tool.log.
Then, make sure that the Mongo service is running and listening on port 27017. If the Mongo service is not running, then the Subscription Asset Manager services cannot start. 
[root@sam-server ~]# service mongod status
[root@sam-server ~]# telnet localhost 27017
If the service is running, check the Mongo database to look for sync entries. For example: 
[root@sam-server ~]# mongo checkin_service --eval "printjson(db.marketing_product_usage.count())"
If neither of those reveal a problem, or if they do not have relevant entries, then run the reporting debug script: 
[root@sam-server ~]# /usr/bin/splice-debug
This collects all relevant configuration and log files for the reporting server and exports the data to a file in the /tmp directory name splice-debug-YYYY-MM-DD-TIME. For example, /tmp/splice-debug-2013-06-14-T15-22-19.
That directory can be zipped and sent to support if necessary.
Q:
Why are all systems marked as invalid?
A:
Check that a manifest has been imported into Subscription Asset Manager for the Satellite server. The manifest tells Subscription Asset Manager what subscriptions the Satellite server has attached to it; without the manifest, reporting assumes that no subscriptions are available.
Q:
I updated subscriptions for a system or my Satellite server in Subscription Asset Manager, but those changes are not being reflected in the report.
A:
The sync script runs every four hours, so it may not have synchronized the changes yet. Either wait for the next scheduled run or run the script by hand (which may take several minutes to finish): 
[root@sam-server ~]# su - splice -s /bin/bash
[splice@sam-server ~]$ spacewalk-splice-checkin
Q:
The link to the Satellite 5.6 UI in the report results is returning an HTTP 404 error.
A:
Verify that the rhn-search process is running on the Satellite 5.6 machine.
2.5.5.3. Other Known Issues
These are some other issues that are recognized with the enhanced reporting and Satellite, but do not have a workaround.
Having Organizations Not Related to Satellite Reporting

If a Subscription Asset Manager instance used in enhanced reporting has non-Satellite organizations added to it, those organizations may be overwritten and removed in the Subscription Asset Manager database as part of the sync process.

Warning

A Subscription Asset Manager instance used for enhanced reporting can only be used as a reporting server for Satellite. It cannot be used a regular Subscription Asset Manager instance to manage systems or data could be lost.