Bug 786843

Copied from https://bugzilla.redhat.com/show_bug.cgi?id=729107#c5


++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

While reviewing this bug, I decided to review Chapter 14 and found the
following issues.

Red_Hat_Enterprise_Linux-Deployment_Guide-5-en-US-7-14

Chapter 14. Product Subscriptions and Entitlements

Red Hat Subscription Manager works with yum to unit content delivery with
subscription management. The Subscription Manager handles only the
subscription-system associations.

[typo] s/unit/unite

...

14.1.1. The Purpose of Subscription Management

Important
Most Red Hat products are licensed under a GNU General Public License (GPL),
which allows free use of the software or code; this a different license than
the Red Hat license agreement.

[typo] Missing "is" in last phrase. It should be "...; this is a different..."

...

14.1.2. Defining Subscriptions, Entitlements, and Products

It's important to distinguish between subscribing to a product and installing a
product. A subscription is essentially a statement of whatever products an
organization has purchased. The act of subscribing to a subscription means that
a system is allowed to install the product with a valid certificate, but
subscribing doesn't actually perform any installation or updates.

[comment] It's, doesn't. Contractions - Do not use, see WUG
https://home.corp.redhat.com/node/67041#c


In the reverse, a product can also be installed apart from any entitlements for
the system; the system is just does not have a valid product certificate.

[typo] "... the systems is just does not..."


Figure 14.3. Relationship Among Systems, the Subscription Service, and Content
Delivery Network

[typo] in the image, "the system is subscribes to the available entitlements"

...

14.1.6. RHN Classic v. Certificate-based Red Hat Network

The two subscription services are mututally exclusive,

[typo] s/mututally/mutually

...

14.2.1. Launching Red Hat Subscription Manager

Red Hat Subscription Manager is listed as one of the administrative tools in
the System => Administration menu in the top management bar.

Figure 14.4. Red Hat Subscription Manager Menu Option

[bug] In RHEL 5.7 and 5.8 Red Hat Subscription Manager is in Applications ->
System Tools. Both the text and the figure need to be updated.

...

14.2.2. About subscription-manager

Any of the operations that can be performed through the Red Hat Subscription
Manager UI can also be performed by running the subscription-manager tool. This
tools has the following format: 

[typo] s/tools/tools

...

14.2.3. Looking at RHN Subscription Management

These tools are somewhat limited in their view; they only disclose information
(such as available entitlements) from the perspective of that one system, so
expired and depleted subscriptions or subscriptions for other architectures
aren't displayed. 

[comment] aren't. Contractions - Do not use, see WUG
https://home.corp.redhat.com/node/67041#c

...

14.3.1. Local Subscription Services, Local Content Providers, and Multi-Tenant
Organizations

These organizations can use different content provider, can have different
subscriptions allocated to them, and can have different users assigned to them
with levels of access set per organization. 

[typo] s/provider/providers


This affects register operations, where the system is registered to
subscription service and then joined to the organization.

[typo] Missing word "...where the system is registered to [a|the] subscription
service..."


For more information on configuring and managing organizations, environments,
and content repositories, see the Subscription Asset Manager documentation. 

[comment] Would be more helpful to define where the SAM documentation is.

...

14.3.2. Virtual Guests and Hosts

- KVM
- Xen
- HyperV
- VMWare ESX 

Subscription Manager records a unique identifier called a guest ID as one of
the system facts for a virtual guest. A special process, libvirt-rhsm, checks
VMWare, KVM, and Xen processes and then relays that information to Subscription
Manager and any configured subscription service (Certificate-based Red Hat
Network or a local Subscription Asset Manager). 

[comment] The list contains 4 hypervisors, but the paragraph on talks about
libvirt-rhsm checking with 3 hypervisors. Is there a reason HyperV is not
mentioned in the paragraph?


Note
The distinction of being a physical machine versus virtual machine matters only
in the priority of how entitlements are consumed. Virtual machines are recorded
in the subscription service inventory as a regular system type of consumer.

Virtual guests are registered to the subscription service inventory as regular
systems and subscribe to entitlements just like any other consumer.

[comment] Paragraph below the note seems like repeated information.

...

14.4.1. Registering Consumers in the Hosted Environment

Systems can also be registered after they've been configured or removed from
the subscription service inventory (unregistered) if they will no longer be
managed within that entitlement system. 

[comment] They've. Contractions - Do not use, see WUG
https://home.corp.redhat.com/node/67041#c

[bug] Images are from RHEL 6 Subscription Manager not RHEL 5.

...

14.4.2. Registering Consumers to a Local Organization

1. Make sure that the rhsm.conf configuration file points to the local
subscription service (in the hostname parameter) and the local content server
(in the baseurl parameter). 

[comment] Would be useful to specify the location of rhsm.conf
(/etc/rhsm/rhsm.conf)


3. Click the Register button at the top of the window in the Tools area. 

[bug] There is no Tools area in RHEL 5 Subscription Manager.


[bug] First three images are from RHEL 6 Subscription Manager not RHEL 5.


NOTE
It is only possible to join an environment during registration. The
environments cannot be changed after registration. 

[comment] "NOTE" is in uppercase. Also, should this really be an "Important"
admonition?

...

14.4.3. Registering an Offline Consumer

Some systems may not have internet connectivity, but administrators still want
to assign and track the subscriptions for that system.

[typo] s/internet/Internet see WUG https://home.corp.redhat.com/node/67041#i

...

14.4.4. Registering from the Command Line

The simplest way to register a machine is to pass the register command with the
user account information required to authenticate to the Certificate-Based Red
Hat Network (the credentials used to access subscription service or the
Customer Portal). 

[typo] s/Certificate-Based/Certificate-based


Example 14.4. Applying Subscriptions During Registration

# subscription-manager register --activationkey=1234abcd --org="IT Dept"

[comment] Example text is pink.

...

14.4.5. Unregistering

In the Red Hat Subscription Manager GUI, there is an Unregister button at the
top of the window in the Tools area. 

[bug] The Tools area does not exist in RHEL 5 Subscription Manager.

[bug] The image is RHEL 6 Subscription Manager.


From the command line, this requires only the unregister. 

[comment] Consider rewording.

...

14.5.1. Installing the Migration Tools

1. The migration tools and data are in supplementary channels. If necessary,
enable the supplementary repositories, as described in Section 14.9, “Working
with Subscription yum Repos”.

[comment] Section 14.9 is written based on Certificate-based subscription. I
don't think you can add the supplementary channels for RHN Classic by following
the instructions in 14.9.

[comment] Is there an SME that can verify this section. I could not verify it
with my rhn account, I had to download subscription-manager-migration and
subscription-manager-migration-data directly from Brew.

...

14.5.2. Migrating from RHN Classic to Certificate-based Red Hat Network

Simply running the rhn-migrate-classic-to-rhsm tool migrates the system profile
and then opens the Subscription Manager GUI so that administrators can assign
subscriptions to the system. 

[comment] This sentences calls "rhn-migrate-classic-to-rhsm" a tool, elsewhere
in this section it is called a script.


The script prompts for the username and password to use to connect to Red Hat
Network. It uses these credentials to authenticate to both Red Hat Network
Classic and Certificatebased Red Hat Network, to verify the account settings.

[typo] s/Certificatebased/Certificate-based


Not every product has a product certificate, so not every channel may have a
map. Only the channels with a certificate channel to a corresponding
certificate map. 

[comment] Last sentence is confusing, consider re-wording.

...

14.5.3. Unregistering from RHN Classic Only

This still copies over the product certificates for the classic channels to
configure the system in the style of certificate-based subscriptions, but it
does not register the machine with subscription service. 

[typo] s/with subscription service/with the subscription service


Because there are product certificates, Subscription Manager will show a red,
invalid status for the system and issue notifications until the system is
registered and subscriptions applied. 

[typo] s/subscriptions applied/subscriptions are applied

...

14.5.4. Migrating a Disconnected System

When Red Hat software is purchased through a vendor, the purchased software is
identified in a installation number or subscription number (described in
https://access.redhat.com/kb/docs/DOC-15408) in the
/etc/sysconfig/rhn/install-num file.

[comment] The final word "file" is unnecessarily emboldened.

...

14.6.1.1. Subscribing to a Product

[bug] Images in this section are of RHEL 6 Subscription Manager.


3. Set the filters to use to search for available entitlements. Subscriptions
can be filtered by their active date and by their name. The checkboxes provide
more fine-grained filtering:

[bug] At the end of this step you need to click "Update" for the subscriptions
to be displayed.


4. Select the available entitlements. To select multiple subscriptions, use the
Ctrl key. 

[comment] The use of the word "entitlement" is confusing here.


5. Click the Subscribe button.

[comment] After this step a window called "Contract Selection" appeared. I had
to select a contract and then click "Subscribe". This is not documented in the
guide, should it be?

...

14.6.3. Stacking Subscriptions

[comment] This section does not tell you how to get to the Contract Selection
screen.

...

14.6.4. Manually Adding a New Subscription

b. In the Tools area, click the Import Certificate button. 

[bug] There is no Tools area in RHEL 5 Subscription Manager.

[bug] Images are for RHEL 6 Subscription Manager.

...

14.7.1. Redeeming Subscriptions through the GUI

2. At the top of the main window, click the Activate Subscription button. 

[bug] Image is for RHEL 6 Subscription Manager.

...

14.7.2. Redeeming Subscriptions on a Machine through the Command Line

[comment] Command text is pink.

...

14.8.1. Viewing Subscriptions in the GUI

The My Installed Software area shows the currently installed products on the
system, along with their subscription status. This doesn't allow administrators
to install software, only to view installed software. 

[comment] Should "My Installed Software area" be referred to as "My Installed
Software tab"?
[comment] doesn't. Contractions - Do not use, see WUG
https://home.corp.redhat.com/node/67041#c

...

14.8.2. Listing Subscriptions with the Command Line

As with the three tabs in the UI, there are three different ways to use the
list command to display different areas of the subscriptions and products on
the system. 

[comment] The text states, "there are three different ways", however, the table
shows five options and lists the --installed option twice.

...

14.9. Working with Subscription yum Repos

The rhn-migrate-classic-to-rhsm uses the information in
/etc/sysconfig/rhn/systemid to get the previous registration information and
map channels to certificates.

[typo] Should the first phrase be, "The rhn-migrate-classic-to-rhsm script
uses..."?


This optional channels must be enabled before the packages in them can be
installed (even if the system is fully entitled to the products in those
channels).

[typo] s/This/These


The repositories can be enabled using the yum-config-managerc ommand:

[typo] s/yum-config-managerc ommand/yum-config-manager command


Alternatively, simply specify the optional or supplimentary repository when
installing a packge with yum. This uses the --enablerepo repo_name option. For
example:

[typo] s/supplimentary/supplementary  s/packge/package

...

14.10. Responding to Subscription Notifications

[bug] Figures 14.19 to 14.22 are for RHEL 6.


When the Subscription Manager UI opens, whether it was opened through a
notification or just opened normally, there is a box in the upper left corner
that shows the number of products that lack a valid certificate. 

[bug] This is for RHEL 6 Subscription Manager.

...

4.11.2. Changing the Healing Check Frequency

NOTE
Healing cannot be disabled by changing the time interval. Setting the
healFrequency parameter to zero means that Subscription Manager simply uses the
default time setting. 

[comment] NOTE is in uppercase.

...

14.12. Working with Subscription Asset Manager

- Creating organizations and environments.
- Creating activation keys.
- Managing subscription manifests from Red Hat.
- Viewing notification and system reports. 

[typo] Periods not required as list items are not full sentences. Chicago 16th
ed sect. 6.124

...

14.12.1. Configuring Subscription Manager to Work with Subscription Asset
Manager

That means that the local Subscription Manager client needs to be configured to
use Subscription Asset Manager as its subcription service and content provider,
rather than using the default Red Hat Network (hosted) configuration. 

[typo] s/subcription/subscription

...

14.14.1.2. About the rhsm.conf File

Two major sections defined the subscription service ([server]) and content and
product delivery ([rhsm]).

[typo] s/defined/define

...

14.14.3.1. Configuring an HTTP Proxy for GUI Use

2. Click the Proxy Configuration button at the top of the window in the Tools
area. 

[bug] There is no Tools area in RHEL 5 Subscription Manager.

[bug] The images in this section are from RHEL 6 Subscription Manager.

...

14.14.7. Starting and Stopping the Subscription Service

1. In the main menu, select the System link and open the Administration
submenu. 

[bug] This is for RHEL 6. In RHEL 5 it is Administration -> Server Settings ->
Services

[bug] Images are for RHEL 6.

...

14.14.10.1. Checking Facts from the Red Hat Subscription Manager UI

2. In the Tools at the top of the window, click the View System Facts button. 

[bug] The Tools area is in RHEL 6 Subscription Manager, not RHEL 5.

...

14.14.10.3. Overriding the Default System Facts

The system facts, as collected, are stored in /var/lib/rhsm/facts/facts.facts. 

[comment] I could not find this file, however, I did see
/var/lib/rhsm/facts/facts.json. Does /var/lib/rhsm/facts/facts.facts exist?

...

14.14.12. Getting the System UUID

[bug] Images is for RHEL 6.