Bug 765905

Summary: add man pages for subscription-manager-migration
Product: Red Hat Enterprise Linux 5 Reporter: Chris Duryee <cduryee>
Component: subscription-managerAssignee: Chris Duryee <cduryee>
Status: CLOSED ERRATA QA Contact: Entitlement Bugs <entitlement-bugs>
Severity: unspecified Docs Contact:
Priority: unspecified    
Version: 5.8CC: jsefler, spandey, wpoteat
Target Milestone: rc   
Target Release: 5.8   
Hardware: Unspecified   
OS: Unspecified   
Whiteboard:
Fixed In Version: Doc Type: Bug Fix
Doc Text:
No description necessary
 Story Points: ---
Clone Of: Environment:
Last Closed: 2012-02-21 06:43:49 UTC Type: ---
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: --- RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: --- Target Upstream Version:
Bug Depends On:    
Bug Blocks: 715031, 769266    

Description Chris Duryee 2011-12-09 16:38:33 UTC 
Description of problem:

The following two man pages need to be added to subscription-manager-migration:

install-num-migrate-to-rhsm
rhn-migrate-classic-to-rhsm

These are already attached to https://bugzilla.redhat.com/show_bug.cgi?id=726407, this BZ is just to get them into the RPM.
Comment 1 Chris Duryee 2011-12-12 18:12:19 UTC 
c08872a765e8f4f069afb7fb20aa9574c8df1bac master 0.98.8+
Comment 2 John Sefler 2011-12-13 03:00:14 UTC 
Verifying Version...
[root@jsefler-onprem-5server tmp]# rpm -q subscription-manager-migration
subscription-manager-migration-0.98.8-1.git.0.c756d75.el5_7


[root@jsefler-onprem-5server tmp]# rpm -ql subscription-manager-migration
/usr/sbin/install-num-migrate-to-rhsm
/usr/sbin/rhn-migrate-classic-to-rhsm
/usr/share/man/man8/install-num-migrate-to-rhsm.8.gz
/usr/share/man/man8/rhn-migrate-classic-to-rhsm.8.gz


[root@jsefler-onprem-5server tmp]# man -P /bin/cat  install-num-migrate-to-rhsm
install-num-migrate-to-rhsm(8)                  install-num-migrate-to-rhsm(8)



NAME
       install-num-migrate-to-rhsm - Checks the installation number for a sys-
       tem and copies over the required product certificates. This is used for
       migrating an offline system to Certificate-based Red Hat Network.


SYNOPSIS
       install-num-migrate-to-rhsm [--dryrun|--instnum=NUMBER|--help]


DESCRIPTION
       install-num-migrate-to-rhsm  migrates  a  system  using  legacy Red Hat
       Enterprise Linux installation numbers to the X.509 certificates used by
       Certificate-based Red Hat Network.


       Access  to  support and updates for products is determined through sub-
       scriptions.  Subscriptions are assigned to a system, which  means  that
       the system has the right to install and update a product with full sup-
       port. Even disconnected or offline systems still need a  way  to  track
       the  products  installed on them and the subscriptions used by them. In
       the older Red Hat Network Classic model of subscription  management,  a
       system was associated with a channel.  In the new Certificate-based Red
       Hat  Network,  installed  products  and  subscriptions  are  identified
       through  X.509  certificates.   Either  way, a channel or a certificate
       provides a means of recognizing and tracking the products and subscrip-
       tions for a system, even an offline system.


       When  Red  Hat  software  is  purchased through a vendor, the purchased
       software is identified in a installation number or subscription number.
       Installation  numbers  are described more in the Knowledgebase article:
       <https://access.redhat.com/kb/docs/DOC-15408>


       This number is located in the /etc/sysconfig/rhn/install-num file.  The
       installation  number  is  in  essence  a code which contains all of the
       information about the products and versions purchased for  the  system.
       For  example,  this installation number shows that it is valid for RHEL
       Client and RHEL Workstation channels.
       [root@server ~]# python /usr/lib/python2.4/site-packages/instnum.py da3122afdb7edd23
       Product: RHEL Client
       Type: Installer Only
       Options: Eval FullProd Workstation
       Allowed CPU Sockets: Unlimited
       Allowed Virtual Instances: Unlimited
       Package Repositories: Client Workstation

       key: 14299426 "da3122"
       checksum: 175 "af"
       options: 4416 "Eval FullProd Workstation"
       socklimit: -1 "Unlimited"
       virtlimit: -1 "Unlimited"
       type: 2 "Installer Only"
       product: 1 "client"

       {"Workstation": "Workstation", "Base": "Client"}


       For an offline system, one which is not connect to either Red Hat  Net-
       work  Classic  (Hosted)  or a Satellite system, the installation number
       can be used to move the subscription configuration from the older chan-
       nel-based  subscription  model to the Certificate-based Red Hat Network
       subscription model, managed by Subscription Manager.


       install-num-migrate-to-rhsm identifies the channel that a  disconnected
       system is subscribed to and then copies in the appropriate product cer-
       tificates.


       This tool is supported for Red Hat Enterprise Linux 5.8 and later.


OPTIONS
       -h, --help
              Prints the specific help information for the given command.


       -d, --dryrun
              Performs a dry run of the script. This  indicates  what  product
              certificates  will  be  copied  into the /usr/share/rhsm/product
              directory, but does not actually copy them over.


       -i NUMBER, --instnum=NUMBER
              Migrates the channels and product certificates based on the man-
              ually-entered  installation  number  rather  than  the number in
              /etc/sysconfig/rhn/install-num.  This  is  an  advanced  option;
              most migrations will use the standard installation number in the
              system configuration.


USAGE
       To pull in the product certificates and migrate the system, simply  run
       the command:

       [root@server ~]# install-num-migrate-to-rhsm


       The  script  copies  in the product certificates that correspond to the
       available channels from the installation number. This script  does  not
       register  the  system  or subscribe the system to any entitlements. For
       the procedure to register an offline system with Certificate-based  Red
       Hat  Network  and  assign  entitlements,  see  the  RHN  documentation:
       <http://docs.redhat.com/docs/en-US/Red_Hat_Customer_Por-
       tal/1/html/Red_Hat_Network_Certificate-based_Subscription_Manage-
       ment/web-consumer-register.html>


       After migration, the system facts maintained  by  Subscription  Manager
       display what script was used for migration.

       [root@server ~]# subscription-manager facts --list | grep migr
       migration.migrated_from: install_number


       Because  the  install-num-migrate-to-rhsm command does not register the
       system with Certificate-based Red Hat Network, the migration  facts  do
       not include a new system ID.



FILES
       /etc/sysconfig/rhn/install-num
              The  16-character  activation  key issued by a vendor which con-
              tains all of the subscription and product  information  for  the
              system. This is used during the installation process.


       /etc/sysconfig/rhn/systemid
              The  digital  server  ID for this machine if the system has been
              registered with Red Hat Network Classic.   This  file  does  not
              exist otherwise.


       /etc/sysconfig/rhn/up2date
              The common configuration file used by RHN client programs.


       /var/log/rhsm/rhsm.log
              The Subscription Manager log file. This contains any errors reg-
              istering the system to Certificate-based Red Hat Network or with
              subscribing the system to entitlements.


       /etc/rhsm/facts/migration.facts
              The  file which contains the migration information. This is dis-
              played as one of the system facts by Subscription Manager.


SEE ALSO
       install-num-migrate-to-rhsm(8), subscription-manager(8).



AUTHORS
       Alex Wood <awood>


BUGS
       Report bugs to <http://bugzilla.redhat.com>.


COPYRIGHT
       Copyright © 2011 Red Hat, Inc.


       This is free software; see the source for copying conditions.  There is
       NO  warranty;  not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
       PURPOSE.



Version 0.1                     December 8 2011 install-num-migrate-to-rhsm(8)




[root@jsefler-onprem-5server tmp]# man -P /bin/cat rhn-migrate-classic-to-rhsm
Formatting page, please wait...
rhn-migrate-classic-to-rhsm(8)                  rhn-migrate-classic-to-rhsm(8)



NAME
       rhn-migrate-classic-to-rhsm  -  Migrates  a system profile from Red Hat
       Network Classic Hosted to Certificate-based Red Hat Network Hosted.


SYNOPSIS
       rhn-migrate-classic-to-rhsm [--force|--cli-only|--help|--no-auto]


DESCRIPTION
       rhn-migrate-classic-to-rhsm migrates a system profile which  is  regis-
       tered  with  Red  Hat Network Classic to Certificate-based Red Hat Net-
       work. This is intended for hosted-to-hosted migrations, not for migrat-
       ing from a Satellite system.


       Access  to  support and updates for products is determined through sub-
       scriptions.  Subscriptions are assigned to a system, which  means  that
       the system has the right to install and update a product with full sup-
       port. Subscriptions for an entire organization are  tracked  through  a
       subscription  service,  either a local Satellite or hosted Red Hat Net-
       work.  The system registers with the subscription service and  receives
       an  inventory  ID number. When subscriptions are allocated to a system,
       it is noted in the subscription service.


       For environments which use a hosted subscription service rather than  a
       local  Satellite  system,  systems were registered with Red Hat Network
       Classic. Red Hat Network Classic, however, has been  replaced  by  Cer-
       tificate-based Red Hat Network. The differences between the two systems
       are  described  in  this  Knowledgebase  article:  <https://access.red-
       hat.com/kb/docs/DOC-45987>


       Registering  with  a  subscription service is exclusive. If a system is
       registered with Red Hat Network Classic, it  cannot  simultaneously  be
       registered  with  Certificate-based  Red  Hat Network. The rhn-migrate-
       classic-to-rhsm tool is provided specifically so that there is a way to
       transition  from the deprecated Red Hat Network Classic to the new Cer-
       tificate-based Red Hat Network.


       This tool is supported for Red Hat Enterprise Linux 5.8 and later.


OPTIONS
       -h, --help
              Prints the specific help information for the given command.


       -f, --force
              Ignore channels not available on Certificate-based Red Hat  Net-
              work.  The channels in Red Hat Network Classic are mapped to the
              product certificates used by Certificate-based Red Hat  Network.
              However,  not every channel has a certificate mapping, which can
              cause errors during migration. Using this option skips any chan-
              nels  which are not mapped to Certificate-based Red Hat Network.


       -c, --cli-only
              Uses subscription-manager register --autosubscribe to apply  all
              relevant subscriptions from Certificate-based Red Hat Network to
              the system automatically.


       -n, --no-auto
              Unsubscribes the system from Red Hat Network  Classic  but  does
              not  subsequently  register  the system to Certificate-based Red
              Hat Network or subscribe the system to any entitlements.


USAGE
       The migration process moves the system from the inventory in  one  sub-
       scription  service  (Red  Hat  Network Classic) to the new subscription
       service (Certificate-based Red Hat Network), and  then  re-applies  the
       subscriptions to the system. The script runs through these steps:


              1. Authenticate to both Red Hat Network Classic and Certificate-
              based Red Hat Network to verify the account settings.


              2. Get a channel list for the system.


              3. Match each channel to a corresponding certificate map.


              4. Copy over the product certificates for the old channels.


              5. Unregister from Red Hat Network Classic.


              6. Register with Certificate-based Red Hat Network.


              7. Open Subscription Manager to subscribe to  the  new  entitle-
              ments. By default, this opens the GUI to allow administrators to
              assign subscriptions manually, but it is also possible to  auto-
              subscribe to the best-matching subscriptions.


       After  migration,  the  system facts maintained by Subscription Manager
       display what script was used for migration and what the previous system
       ID was.
       [root@server ~]# subscription-manager facts --list | grep migr
       migration.classic_system_id: 09876
       migration.migrated_from: rhn_hosted_classic


   BASIC MIGRATION
       Simply running the rhn-migrate-classic-to-rhsm tool migrates the system
       profile and then open the Subscription Manager GUI so that  administra-
       tors can assign subscriptions to the system.


       The script prompts for the RHN username and password for the user; this
       same account is used to authenticate with both Red Hat Network  Classic
       and Certificate-based Red Hat Network.

       [root@server ~]# rhn-migrate-classic-to-rhsm
       RHN Username: jsmith
       Password:

       Retrieving existing RHN classic subscription information ...
       +----------------------------------+
       System is currently subscribed to:
       +----------------------------------+
       rhel-i386-client-5

       List of channels for which certs are being copied
       rhel-i386-client-5

       Product Certificates copied successfully to /etc/pki/product !!

       Preparing to unregister system from RHN classic ...
       System successfully unregistered from RHN Classic.

       Attempting to register system to Certificate-based RHN ...
       The system has been registered with id: abcd1234
       System server.example.com successfully registered to Certificate-based RHN.

       Launching the GUI tool to manually subscribe the system ...


   MIGRATION AND AUTOSUBSCRIBE
       Instead  of  opening  the Subscription Manager GUI after migration, the
       rhn-migrate-classic-to-rhsm tool can use the Subscription  Manager  CLI
       to  autosubscribe  the  system to the best-matching subscriptions. This
       allows migrations to be fully automated, without  administrator  inter-
       vention.

       [root@server ~]# rhn-migrate-classic-to-rhsm --cli-only
       RHN Username: jsmith
       Password:


       Retrieving existing RHN classic subscription information ...
       +----------------------------------+
       System is currently subscribed to:
       +----------------------------------+
       rhel-i386-client-5

       List of channels for which certs are being copied
       rhel-i386-client-5

       Product Certificates copied successfully to /etc/pki/product !!

       Preparing to unregister system from RHN classic ...
       System successfully unregistered from RHN Classic.

       Attempting to register system to Certificate-based RHN ...
       The system has been registered with id: abcd1234
       System ’server.example.com’ successfully registered to Certificate-based RHN.

       Attempting to auto-subscribe to appropriate subscriptions ...
       Installed Product Current Status:
       ProductName:            Red Hat Enterprise Linux Desktop
       Status:                 Subscribed

       Successfully subscribed.

       Please visit https://access.redhat.com/management/consumers/abcd1234 to view the details, and to make changes if necessary.


   UNREGISTER FROM RED HAT NETWORK CLASSIC ONLY
       The rhn-migrate-classic-to-rhsm tool can be used simply to unregister a
       system from Red Hat Network Classic without registering it to  Certifi-
       cate-based Red Hat Network or assigning subscriptions to the system.

       [root@server ~]# rhn-migrate-classic-to-rhsm --no-auto
       RHN Username: jsmith
       Password:

       Retrieving existing RHN classic subscription information ...
       +----------------------------------+
       System is currently subscribed to:
       +----------------------------------+
       rhel-i386-client-5

       List of channels for which certs are being copied
       rhel-i386-client-5

       Product Certificates copied successfully to /etc/pki/product !!

       Preparing to unregister system from RHN classic ...
       System successfully unregistered from RHN Classic.



FILES
       /etc/sysconfig/rhn/systemid
              The  digital  server  ID for this machine if the system has been
              registered with Red Hat Network Classic.   This  file  does  not
              exist otherwise.


       /etc/sysconfig/rhn/up2date
              The common configuration file used by RHN client programs.


       /var/log/rhsm/rhsm.log
              The Subscription Manager log file. This contains any errors reg-
              istering the system to Certificate-based Red Hat Network or with
              subscribing the system to entitlements.


       /etc/rhsm/facts/migration.facts
              The  file which contains the migration information. This is dis-
              played as one of the system facts by Subscription Manager.


SEE ALSO
       install-num-migrate-to-rhsm(8), subscription-manager(8).



AUTHORS
       Paresh Mutha <pmutha>, Mark Huth  <mhuth>,  Tasos
       Papaioannou <tpapaioa>


BUGS
       Report bugs to <http://bugzilla.redhat.com>.


COPYRIGHT
       Copyright © 2011 Red Hat, Inc.


       This is free software; see the source for copying conditions.  There is
       NO warranty; not even for MERCHANTABILITY or FITNESS FOR  A  PARTICULAR
       PURPOSE.



Version 0.2                     December 8 2011 rhn-migrate-classic-to-rhsm(8)
[root@jsefler-onprem-5server tmp]# 



AS SHOWN ABOVE, THE MAN PAGES FOR install-num-migrate-to-rhsm AND rhn-migrate-classic-to-rhsm ARE SUCCESSFULLY INSTALLED WITH THE subscription-manager-migration PACKAGE.  SEPARATE BUGS SHOULD BE OPENED AGAINST THE CONTENT OF THE MAN PAGES.

Moving this bug to VERIFIED
Comment 3 William Poteat 2012-01-23 15:53:07 UTC 
    Technical note added. If any revisions are required, please edit the "Technical Notes" field
    accordingly. All revisions will be proofread by the Engineering Content Services team.
    
    New Contents:
No description necessary
Comment 4 errata-xmlrpc 2012-02-21 06:43:49 UTC 
Since the problem described in this bug report should be
resolved in a recent advisory, it has been closed with a
resolution of ERRATA.

For information on the advisory, and where to find the updated
files, follow the link below.

If the solution does not work for you, open a new bug report.

http://rhn.redhat.com/errata/RHBA-2012-0154.html