Preupgrade Assistant Purpose
----------------------------
The Preupgrade Assistant performs an assessment of the system from
the "upgradeability" point of view. Such an analysis includes checking for removed
packages, packages replaced by partially incompatible packages, changes in
libraries, users and groups and various services. The report of this analysis
can help the admin with the in-place upgrade - by identifying potential
troubles and by mitigating some of the incompatibilities. The data gathered
by the Preupgrade Assistant can be used for "cloning" the system - a new,
clean installation of the system, as close as possible to the old Red Hat Enterprise Linux setup.
In addition, it provides some postupgrade scripts which are supposed to finish the
migration after the installation of Red Hat Enterprise Linux 7 system.

As the Preupgrade Assistant does not modify the assessed system directly
(except storing information/logs), it is safe to use on any configuration.
As the modules are not complete yet, a successful Preupgrade Assistant analysis
does not necessarily mean that the in-place upgrade via redhat-upgrade-tool will succeed.

Preupgrade Assistant Usage
--------------------------
At the moment, only a CLI interface and limited functionality is available.

Follow these steps to use the Preupgrade Assistant:
1) Run "preupg -l" command - it lists all available modules for
        preupgrade-assistant (as the system is based on a plug-in, there might be
        modules from different sources in the future). If nothing is shown,
        install the preupgrade-assistant modules package.
2) If you have RHEL6_7 modules available, run "preupg -s RHEL6_7"
3) Wait until the analysis finishes (it can take several minutes)
4) Review the report stored as /root/preupgrade/result.html (and possibly
       the files stored at /root/preupgrade) . Especially check for any in-place
        upgrade risks (as described further in this document).

The /root/preupgrade file&directory structure
------------------------------------

This directory contains the data from the last Preupgrade Assistant run.
The files are:
result.html - a file with the final migration assessment report in a human-readable
         form (the functionality is only listed)
result.xml - a file with the final migration assessment report in a machine-readable form
result-admin.html - a file with the final migration assessment report in a human-readable
         form (the functionality is only listed) for administrators
result-admin.xml - a file with final the migration assessment report in a machine-readable 
         form for administrators
result-admin.html - a file with the final migration assessment report in a human-readable
         form (the functionality is only listed) for users
result-admin.xml - a file with the final migration assessment report in a machine-readable 
         form for users
README - this file
results.tar.gz - a tarball with all the files in the /root/preupgrade directory

The directories are:
cleanconf - a directory with all user-modified configuration files, which were
          checked for the compatibility by the Preupgrade Assistant. These files
          can be safely used on Red Hat Enterprise Linux 7 system (some of these files might need
          a postupgrade.d scripts execution).
dirtyconf - a directory with all user-modified configuration files, which were not
          checked for the compatibility by the Preupgrade Assistant. These might
          require an admin review after the Red Hat Enterprise Linux 7 installation/upgrade.
kickstart - a directory with various files needed for generating
          Kickstart used to clone the system. See the README file
          in the kickstart directory for the file descriptions.
postupgrade.d - contains various scripts which are supposed to be executed
          AFTER the upgrade to Red Hat Enterprise Linux 7. These scripts should NEVER be used
          on the Red Hat Enterprise Linux 6 system.
RHEL6_7 - just a "debugging" directory - will be removed later. Ignore, unless you see an "Error" plug-in exit status.

Possible exit codes explanation
-------------------------------------
Every single plug-in has its own exit code. The administrator needs to check
at least those with a FAIL result before starting the in-place upgrade. The FIXED results
should be checked after the in-place upgrade - to finish the Red Hat Enterprise Linux 7 upgrade
properly.

The possible exit codes are:
 * PASS = everything is fine, no incompatibilities/issues detected 
 * FAIL = an incompatibility/issue that needs to be reviewed by the admin was detected
          FAIL does not necessarily mean that the in-place upgrade will fail, but might
          result in a not 100% functional system
 * FIXED = an incompatibility was detected, but the Preupgrade Assistant was able
          to find an automated solution. Some of the fixes may require running
          postupgrade.d scripts after the upgrade. The fixed configs are available
          in the /root/preupgrade/cleanconf directory. The Preupgrade Assistant does not
          handle the fixes automatically at the moment.
 * INFORMATIONAL = nice to have information for admins (e.g. removed options
          in some common tools which could cause malfunctions of their scripts)
 * NOT_APPLICABLE = the package which was to be tested by the check is not
          installed on the system 
 * ERROR = it is not expected to occur and usually means an error in the Preupgrade Assistant
          framework. All such errors should be reported to the Red Hat
          Preupgrade Assistant team.

In-place upgrade risk explanations
-----------------------------------
There are several levels of in-place upgrade risks. Any level higher than
"slight" means you will get a not 100% functional upgraded system, although the
in-place upgrade tool "redhat-upgrade-tool" may pass.

The available risk assessment levels are:
 * None - Default. It can be used as an indicator for some checks. It is not
          necessary to enter these values.
 * Slight - We assessed this field and have not found any issues. However,
          there is still a risk that not all variants have been covered.
 * Medium - It is likely that the area will cause a problem in the case of the in-place
          upgrade. It needs to be checked by the administrator after
          the in-place upgrade and after the system was monitored for
          some time.
 * High - The in-place upgrade cannot be used safely without the administrator's
          assistance. This typically involves some known broken scenario,
          existing 3rd party packages. After the administrator manually fixes
          the issue, it should be possible to perform the in-place upgrade, but it
          is not recommended.
 * Extreme - We found an incompatibility which makes the in-place upgrade
          impossible. It is recommended to install a new system with the help
          of the Preupgrade Assistant remediations.
