| Summary: | man page for rhn-migrate-classic-to-rhsm needs a description for new option --remove-rhn-packages | ||
|---|---|---|---|
| Product: | Red Hat Enterprise Linux 6 | Reporter: | John Sefler <jsefler> |
| Component: | subscription-manager | Assignee: | Kevin Howell <khowell> |
| Status: | CLOSED ERRATA | QA Contact: | John Sefler <jsefler> |
| Severity: | low | Docs Contact: | |
| Priority: | medium | ||
| Version: | 6.9 | CC: | csnyder, khowell, redakkan, skallesh, vrjain |
| Target Milestone: | rc | Keywords: | EasyFix, Triaged |
| Target Release: | --- | ||
| Hardware: | Unspecified | ||
| OS: | Unspecified | ||
| Whiteboard: | |||
| Fixed In Version: | Doc Type: | If docs needed, set a value | |
| Doc Text: | Story Points: | --- | |
| Clone Of: | Environment: | ||
| Last Closed: | 2017-03-21 10:56:49 UTC | Type: | Bug |
| Regression: | --- | Mount Type: | --- |
| Documentation: | --- | CRM: | |
| Verified Versions: | Category: | --- | |
| oVirt Team: | --- | RHEL 7.3 requirements from Atomic Host: | |
| Cloudforms Team: | --- | Target Upstream Version: | |
|
Description
John Sefler
2016-11-01 17:38:05 UTC
Existing man page...
[root@jsefler-rhel6 ~]# rpm -q subscription-manager-migration-data
subscription-manager-migration-data-2.0.32-1.el6.noarch
[root@jsefler-rhel6 ~]# man -P cat rhn-migrate-classic-to-rhsm
rhn-migrate-classic-to-rhsm(8) Migration Tool rhn-migrate-classic-to-rhsm(8)
NAME
rhn-migrate-classic-to-rhsm - Migrates a system profile from Red Hat
Network Classic Hosted to Customer Portal Subscription Management
(hosted) or Subscription Asset Manager (on-premise).
SYNOPSIS
rhn-migrate-classic-to-rhsm [--force] | [--no-auto] [--keep] |
[--servicelevel=SERVICE_LEVEL] | [--destination-url=URL] |
[--legacy-user=LEGACY_USER] | [--legacy-password=LEGACY_PASSWORD] |
[--destination-user=DESTINATION_USER] | [--destination-password=DES-
TINATION_PASSWORD] | [--org=ORG] | [--environment=ENVIRONMENT] |
[--no-proxy] [--activation-key=ACTIVATION_KEY] | [--help]
DESCRIPTION
rhn-migrate-classic-to-rhsm migrates a system profile which is reg-
istered with Red Hat Network Classic to Customer Portal Subscription
Management. This is intended for migrating from the host service,
not for migrating from a Satellite system.
This script migrates configuration, from a channel-based subscrip-
tion framework to a certificate-based subscription framework. While
the rhn-migrate-classic-to-rhsm script performs the migration opera-
tion, the data used to map the channels to the corresponding product
certificates is defined in the subscription-manager-migration-data
package. The subscription-manager-migration-data package must be
installed before the rhn-migrate-classic-to-rhsm script can be run
successfully.
BACKGROUND
Access to support and updates for products is determined through
subscriptions. Subscriptions are attached to a system, which means
that the system has the right to install and update a product with
full support. Subscriptions for an entire account are tracked
through a subscription management service.
With the channel-based framework, a subscription management service
was either an on-premise Satellite or hosted Red Hat Network Clas-
sic. With the new certificate-based subscriptions, the subscription
management service is either Customer Portal Subscription Management
or Subscription Asset Manager. The differences between the two types
of subscription management services are described in this Knowledge-
base article: <https://access.redhat.com/knowledge/articles/63269>
The system registers with the subscription management service and
receives an inventory ID number. When subscriptions are attached to
a system, that association is noted in the subscription management
service.
Registering with a subscription management service is exclusive. If
a system is registered with Red Hat Network Classic, it cannot
simultaneously be registered with Customer Portal Subscription Man-
agement. The rhn-migrate-classic-to-rhsm tool is provided specifi-
cally so that there is a way to transition from the deprecated Red
Hat Network Classic to Customer Portal Subscription Management or an
on-premise Subscription Asset Manager.
OPTIONS
-h, --help
Prints the specific help information for the given command.
-f, --force
Ignore channels not available through Customer Portal Sub-
scription Management (or Subscription Asset Manager). The
channels in Red Hat Network Classic are mapped to the product
certificates used by the Customer Portal Subscription Manage-
ment. However, not every channel has a certificate mapping,
which can cause errors during migration. Using this option
skips any channels which are not mapped to Customer Portal
Subscription Management.
-n, --no-auto
Deletes the system from Red Hat Network Classic and registers
it to Customer Portal Subscription Management, but does not
attach any subscriptions to the system.
-s SERVICE_LEVEL, --servicelevel=SERVICE_LEVEL
Sets a preferred service level for the system, such as pre-
mium or standard. This service-level preference is then used
as one of the criteria for auto-attaching subscriptions to
the system.
--org=ORG
Sets the organization within the account structure to which
to register the system. Every account is divided into sub-
groups called organizations, which represent some kind of
organizational or logical division in the infrastructure.
Organizations are further divided into environments, which
organize content streams.
--environment=ENVIRONMENT
Sets which environment within the organization the system
belongs to. Every account is divided into subgroups called
organizations, which are further divided into environments
Environments define different content streams.
--activation-key=ACTIVATION_KEY
Sets an activation key to use during registration to the sub-
scription management service. Use of an activation key
requires the user to supply the organization that the system
will be registered to. This option may be supplied multiple
times.
--keep Leaves the system profile on the legacy system. Normally the
system profile on the legacy system is deleted.
--no-proxy
Disables or ignores any previous RHN proxy settings when
migrating to the new subscription management service.
--legacy-user=LEGACY_USER
Specifies the user name on the legacy server.
--legacy-password=LEGACY_PASSWORD
Specifies the password for the user on the legacy server.
--destination-url=URL
Specifies the URL of the subscription management service to
which to register the system. This is used for environments
which have an on-premise subscription management service such
as Subscription Asset Manager. If no URL is given, the migra-
tion tool uses the Customer Portal Subscription Management
Service.
--destination-user=DESTINATION_USER
Specifies the user name on the destination server.
--destination-password=DESTINATION_PASSWORD
Specifies the password for the user on the destination
server.
USAGE
The migration process moves the system from the inventory in one
subscription management service (Red Hat Network Classic) to the new
subscription management service (Customer Portal Subscription Man-
agement), and then re-applies the subscriptions to the system. The
script runs through these steps:
1. Authenticate to both Red Hat Network Classic and Customer
Portal Subscription Management to verify the account set-
tings.
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 Customer Portal Subscription Management and
auto-attach the best-matched 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
migration.migration_date: 2012-09-14T14:55:29.280519
MIGRATION AND AUTOSUBSCRIBE
The rhn-migrate-classic-to-rhsm tool, by default, auto-attaches the
best-matching subscriptions to the system. This allows migrations to
be automated.
[root@server ~]# rhn-migrate-classic-to-rhsm
Legacy username: jsmith.com
Legacy password:
Retrieving existing legacy subscription information...
+-----------------------------------------------------+
System is currently subscribed to these legacy channels:
+-----------------------------------------------------+
rhel-x86_64-server-6
+-----------------------------------------------------+
Installing product certificates for these legacy channels:
+-----------------------------------------------------+
rhel-x86_64-server-6
Product certificates installed successfully to /etc/pki/product.
Preparing to unregister system from legacy server...
System successfully unregistered from legacy server.
Attempting to register system to destination server...
The system has been registered with ID: e6876d95-3564-4506-a44e-cb0c1b651434
Installed Product Current Status:
Product Name: Red Hat Enterprise Linux Server
Status: Subscribed
System ’jsmith.rhn.example.com’ successfully registered.
The script prompts for a username and password to use to register
the system; this same account is used to authenticate with both Red
Hat Network Classic and Customer Portal Subscription Management.
Optionally, the --servicelevel argument sets an SLA preference to
use with the system. The SLA associated with a subscription is then
evaluated when determining what subscriptions to auto-attach to the
system, along with other factors like installed products, existing
channel assignments, and architecture.
[root@server ~]# rhn-migrate-classic-to-rhsm --servicelevel=premium
Legacy username: jsmith.com
Legacy password:
MIGRATION TO ON-PREMISE SERVICES
The rhn-migrate-classic-to-rhsm tool migrates the system to Customer
Portal Subscription Management (hosted) services by default. This
uses the default configuration for Subscription Manager, which
points to the subscription management services for the Customer Por-
tal. For infrastructures which have an on-premise subscription man-
agement service such as Subscription Asset Manager, this configura-
tion can be changed so that the migration process registers the sys-
tems to the on-premise subscription management service and attaches
the appropriate subscriptions.
This is done by using the --destination-url option, which specifies
the URL of the on-premise service. In this case, the authorization
credentials must also be given for the on-premise subscription man-
agement service account (which is independent of the RHN classic
account).
[root@server ~]# rhn-migrate-classic-to-rhsm --destination-url=sam.example.com
Legacy username: jsmith.com
Legacy password:
Destination username: jsmith.com
Destination password:
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
registering the system to Customer Portal Subscription Man-
agement or with attaching subscriptions to the system.
subscription-manager-migration-data.rpm
The package which contains the mappings for the migration
script to migrate channels to the appropriate product cer-
tificates.
SEE ALSO
install-num-migrate-to-rhsm(8), subscription-manager(8).
AUTHORS
Deon Lackey <dlackey>, Paresh Mutha <pmutha>,
Mark Huth <mhuth>, Tasos Papaioannou <tpapaioa@red-
hat.com>
BUGS
This script is part of the Red Hat Subscription Manager tool. Report
bugs to <http://bugzilla.redhat.com>, using the Red Hat Enterprise
Linux product and the subscription-manager component.
COPYRIGHT
Copyright © 2012 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 PAR-
TICULAR PURPOSE.
rhn-migrate-classic-to-rhsm(8)
Should also include --remove-rhn-packages in the SYNOPSIS Retested on;
# subscription-manager version
server type: This system is currently not registered.
subscription management server: 0.9.51.11-1
subscription management rules: 5.15
subscription-manager: 1.18.6-1.el6
python-rhsm: 1.18.6-1.el6
# rpm -qa subscription-manager*
subscription-manager-migration-1.18.6-1.el6.x86_64
subscription-manager-firstboot-1.18.6-1.el6.x86_64
subscription-manager-1.18.6-1.el6.x86_64
subscription-manager-gui-1.18.6-1.el6.x86_64
subscription-manager-migration-data-2.0.32-1.el6.noarch
Issues reported in the bugzilla are now added :
1) Option "[--remove-rhn-packages] " is now displayed in the synopsis section
SYNOPSIS
rhn-migrate-classic-to-rhsm [--force] | [--no-auto] [--keep] | [--servicelevel=SERVICE_LEVEL] | [--remove-rhn-packages] | [--destination-url=URL] | [--legacy-user=LEGACY_USER] | [--legacy-password=LEGACY_PASSWORD] | [--destination-user=DESTINATION_USER] | [--destination-password=DESTINATION_PASSWORD] | [--org=ORG] | [--environment=ENVIRONMENT] | [--no-proxy][--activation-key=ACTIVATION_KEY] | [--help]
2) "Options" section was updated and now includes --remove-rhn-packages option
--remove-rhn-packages
After unregistering from Red Hat Network Classic, remove legacy packages: osad, rhn-check, rhn-client-tools, rhncfg, rhncfg-actions, rhncfg-client, rhncfg-management, rhn-setup, rhnpush, rhnsd, spacewalk-abrt, spacewalk-oscap, yum-rhn-plugin. Once unregistered from Red Hat Network Classic, they are no longer needed. Once packages are removed,subsequent attempts to migrate will be blocked with a message indicating "Perhaps this script was already executed with --remove-rhn-packages?". --remove-rhn-packages cannot be used with --keep, since it does not make sense to keep a system registered without the tooling.
3) "Usage" section was updated , step 6 now shows " Stop and disable legacy services: osad, rhnsd."
5. Unregister from Red Hat Network Classic.
6. Stop and disable legacy services: osad, rhnsd.
7. Register with Customer Portal Subscription Management and auto-attach the best-matched subscriptions.
Above retest steps demonstrates that all the issues reported in the bugzilla are now fixed. Marking as Verified.
Note: Entire man page entry
===========================
man -P cat rhn-migrate-classic-to-rhsm
rhn-migrate-classic-to-rhsm(8) Migration Tool rhn-migrate-classic-to-rhsm(8)
NAME
rhn-migrate-classic-to-rhsm - Migrates a system profile from Red Hat Network Classic Hosted to Customer Portal Subscription Management (hosted) or Subscription Asset Manager (on-
premise).
SYNOPSIS
rhn-migrate-classic-to-rhsm [--force] | [--no-auto] [--keep] | [--servicelevel=SERVICE_LEVEL] | [--remove-rhn-packages] | [--destination-url=URL] | [--legacy-user=LEGACY_USER] |
[--legacy-password=LEGACY_PASSWORD] | [--destination-user=DESTINATION_USER] | [--destination-password=DESTINATION_PASSWORD] | [--org=ORG] | [--environment=ENVIRONMENT] | [--no-proxy]
[--activation-key=ACTIVATION_KEY] | [--help]
DESCRIPTION
rhn-migrate-classic-to-rhsm migrates a system profile which is registered with Red Hat Network Classic to Customer Portal Subscription Management. This is intended for migrating from
the host service, not for migrating from a Satellite system.
This script migrates configuration, from a channel-based subscription framework to a certificate-based subscription framework. While the rhn-migrate-classic-to-rhsm script performs
the migration operation, the data used to map the channels to the corresponding product certificates is defined in the subscription-manager-migration-data package. The subscription-
manager-migration-data package must be installed before the rhn-migrate-classic-to-rhsm script can be run successfully.
BACKGROUND
Access to support and updates for products is determined through subscriptions. Subscriptions are attached to a system, which means that the system has the right to install and
update a product with full support. Subscriptions for an entire account are tracked through a subscription management service.
With the channel-based framework, a subscription management service was either an on-premise Satellite or hosted Red Hat Network Classic. With the new certificate-based subscrip-
tions, the subscription management service is either Customer Portal Subscription Management or Subscription Asset Manager. The differences between the two types of subscription man-
agement services are described in this Knowledgebase article: <https://access.redhat.com/knowledge/articles/63269>
The system registers with the subscription management service and receives an inventory ID number. When subscriptions are attached to a system, that association is noted in the sub-
scription management service.
Registering with a subscription management service is exclusive. If a system is registered with Red Hat Network Classic, it cannot simultaneously be registered with Customer Portal
Subscription Management. 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 Customer
Portal Subscription Management or an on-premise Subscription Asset Manager.
OPTIONS
-h, --help
Prints the specific help information for the given command.
-f, --force
Ignore channels not available through Customer Portal Subscription Management (or Subscription Asset Manager). The channels in Red Hat Network Classic are mapped to the prod-
uct certificates used by the Customer Portal Subscription Management. However, not every channel has a certificate mapping, which can cause errors during migration. Using this
option skips any channels which are not mapped to Customer Portal Subscription Management.
-n, --no-auto
Deletes the system from Red Hat Network Classic and registers it to Customer Portal Subscription Management, but does not attach any subscriptions to the system.
-s SERVICE_LEVEL, --servicelevel=SERVICE_LEVEL
Sets a preferred service level for the system, such as premium or standard. This service-level preference is then used as one of the criteria for auto-attaching subscriptions
to the system.
--remove-rhn-packages
After unregistering from Red Hat Network Classic, remove legacy packages: osad, rhn-check, rhn-client-tools, rhncfg, rhncfg-actions, rhncfg-client, rhncfg-management, rhn-
setup, rhnpush, rhnsd, spacewalk-abrt, spacewalk-oscap, yum-rhn-plugin. Once unregistered from Red Hat Network Classic, they are no longer needed. Once packages are removed,
subsequent attempts to migrate will be blocked with a message indicating "Perhaps this script was already executed with --remove-rhn-packages?". --remove-rhn-packages cannot
be used with --keep, since it does not make sense to keep a system registered without the tooling.
--org=ORG
Sets the organization within the account structure to which to register the system. Every account is divided into subgroups called organizations, which represent some kind of
organizational or logical division in the infrastructure. Organizations are further divided into environments, which organize content streams.
--environment=ENVIRONMENT
Sets which environment within the organization the system belongs to. Every account is divided into subgroups called organizations, which are further divided into environments
Environments define different content streams.
--activation-key=ACTIVATION_KEY
Sets an activation key to use during registration to the subscription management service. Use of an activation key requires the user to supply the organization that the sys-
tem will be registered to. This option may be supplied multiple times.
--keep Leaves the system profile on the legacy system. Normally the system profile on the legacy system is deleted.
--no-proxy
Disables or ignores any previous RHN proxy settings when migrating to the new subscription management service.
--legacy-user=LEGACY_USER
Specifies the user name on the legacy server.
--legacy-password=LEGACY_PASSWORD
Specifies the password for the user on the legacy server.
--destination-url=URL
Specifies the URL of the subscription management service to which to register the system. This is used for environments which have an on-premise subscription management ser-
vice such as Subscription Asset Manager. If no URL is given, the migration tool uses the Customer Portal Subscription Management Service.
--destination-user=DESTINATION_USER
Specifies the user name on the destination server.
--destination-password=DESTINATION_PASSWORD
Specifies the password for the user on the destination server.
USAGE
The migration process moves the system from the inventory in one subscription management service (Red Hat Network Classic) to the new subscription management service (Customer Portal
Subscription Management), and then re-applies the subscriptions to the system. The script runs through these steps:
1. Authenticate to both Red Hat Network Classic and Customer Portal Subscription Management 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. Stop and disable legacy services: osad, rhnsd.
7. Register with Customer Portal Subscription Management and auto-attach the best-matched 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
migration.migration_date: 2012-09-14T14:55:29.280519
MIGRATION AND AUTOSUBSCRIBE
The rhn-migrate-classic-to-rhsm tool, by default, auto-attaches the best-matching subscriptions to the system. This allows migrations to be automated.
[root@server ~]# rhn-migrate-classic-to-rhsm
Legacy username: jsmith.com
Legacy password:
Retrieving existing legacy subscription information...
+-----------------------------------------------------+
System is currently subscribed to these legacy channels:
+-----------------------------------------------------+
rhel-x86_64-server-6
+-----------------------------------------------------+
Installing product certificates for these legacy channels:
+-----------------------------------------------------+
rhel-x86_64-server-6
Product certificates installed successfully to /etc/pki/product.
Preparing to unregister system from legacy server...
System successfully unregistered from legacy server.
Attempting to register system to destination server...
The system has been registered with ID: e6876d95-3564-4506-a44e-cb0c1b651434
Installed Product Current Status:
Product Name: Red Hat Enterprise Linux Server
Status: Subscribed
System ’jsmith.rhn.example.com’ successfully registered.
The script prompts for a username and password to use to register the system; this same account is used to authenticate with both Red Hat Network Classic and Customer Portal Sub-
scription Management.
Optionally, the --servicelevel argument sets an SLA preference to use with the system. The SLA associated with a subscription is then evaluated when determining what subscriptions to
auto-attach to the system, along with other factors like installed products, existing channel assignments, and architecture.
[root@server ~]# rhn-migrate-classic-to-rhsm --servicelevel=premium
Legacy username: jsmith.com
Legacy password:
MIGRATION TO ON-PREMISE SERVICES
The rhn-migrate-classic-to-rhsm tool migrates the system to Customer Portal Subscription Management (hosted) services by default. This uses the default configuration for Subscription
Manager, which points to the subscription management services for the Customer Portal. For infrastructures which have an on-premise subscription management service such as Subscrip-
tion Asset Manager, this configuration can be changed so that the migration process registers the systems to the on-premise subscription management service and attaches the appropri-
ate subscriptions.
This is done by using the --destination-url option, which specifies the URL of the on-premise service. In this case, the authorization credentials must also be given for the on-
premise subscription management service account (which is independent of the RHN classic account).
[root@server ~]# rhn-migrate-classic-to-rhsm --destination-url=sam.example.com
Legacy username: jsmith.com
Legacy password:
Destination username: jsmith.com
Destination password:
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 registering the system to Customer Portal Subscription Management or with attaching subscriptions to the system.
subscription-manager-migration-data.rpm
The package which contains the mappings for the migration script to migrate channels to the appropriate product certificates.
SEE ALSO
install-num-migrate-to-rhsm(8), subscription-manager(8).
AUTHORS
Deon Lackey <dlackey>, Paresh Mutha <pmutha>, Mark Huth <mhuth>, Tasos Papaioannou <tpapaioa>
BUGS
This script is part of the Red Hat Subscription Manager tool. Report bugs to <http://bugzilla.redhat.com>, using the Red Hat Enterprise Linux product and the subscription-manager
component.
COPYRIGHT
Copyright © 2012 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.
rhn-migrate-classic-to-rhsm(8)
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. https://rhn.redhat.com/errata/RHSA-2017-0698.html |