preupgrade-assistant-api(1)

NAME
preupgrade-assistant-api - Preupgrade assistant API provides a set of functions and variables which can be used for contents writing.

AVAILABLE FUNCTIONS
API provides a set of functions which can be used for better handling of your data. check_applies_to - Function can be used for specific RPM package detection. If the RPM package does not exists then check script exit with exit_not_applicable return code. check_root - Function checks whether user is root. solution_file - Function adds a message to solution file defined in INI file. backup_config_file - Function backups a config file to /root/preupgrade directory. service_is_enabled - Function checks if service provided by command chkconfig is enabled.

COMMON_DATA
There are several log files gathered before an assessment: $VALUE_RPM_QA - all packages with RSA HEADER and php signature $VALUE_ALL_CHANGED - all changed package files $VALUE_CONFIGCHANGED - all changed configuration files $VALUE_RPM_RHSIGNED - all RPM Packages signed by RedHat $VALUE_PASSWD - file with all users $VALUE_GROUP - file with all groups $VALUE_CHKCONFIG - file with chkconfig output $VALUE_TPM_PREUPGRADE - directory used for storing your data (like kickstart, postupgrade.d directories) $VALUE_ALLMYFILES - all local files $VALUE_EXECUTABLES - all executables files $MIGRATE - set to 1 if migration mode is specified by module $UPGRADE - set to 1 if upgrade mode is specified by module There are several directories located in /root/preupgrade which are used by preupg command kickstart - used for kickstart generation. etc - stored configuration files copied by modules. postupgrade.d - stored scripts which are executed after an upgrade. preupgrade-scripts - stored scripts which are executed before an upgrade. common - the results of long term commands gathered before an assessment

RETURN CODES
exit_pass - The test passed. Use if nothing "broken" was detected exit_not_applicable - Rule did not apply to test target. (e.g. package is not installed). Useful if pripare requirements are not met. exit_informational - Rule was evaluated by the checking engine, but isn't to be scored. Ideal for informational results, which have "migration guide" chapter style. exit_fixed - Rule failed, but was later fixed. Ideal if you automatically fixed some configuration file/incompatibility, no manual review expected, but still we should notify the user. exit_unknown - Could not tell what happened. Don't know when this should be used ;). exit_error - An error occurred and test could not complete. (script failed while doing its job). Should be used in "assert way", not as common result. exit_fail - The test failed. (moving to new release with this configuration will result in malfunction). Use when you expect some action from the user - when the migration solution was not completed automatically. Your script should also tell the administrator how risky is to upgrade your component. This can be done with api functions log_{none,slight,medium,high,extreme}_risk.

AVAILABLE RETURN CODES IN REPORTS
pass - The same as in RETURN CODES not_applicable - Rule did not apply to test target. (e.g. package is not installed). Useful if pripare requirements are not met. informational - Rule was evaluated by the checking engine, but isn't to be scored. Ideal for informational results, which have "migration guide" chapter style. fixed - Rule failed, but was later fixed. Ideal if you automatically fixed some configuration file/incompatibility, no manual review expected, but still we should notify the user. unknown - Could not tell what happened. Don't know when this should be used ;). error - An error occurred and test could not complete. (script failed while doing its job). Should be used in "assert way", not as common result. needs_inspection - The test failed with return code exit_fail. But content developer add one of these logs (log_{medium|slight|None}_risk before exit_fail. needs_action - The test failed with return code exit_fail. But content developer add the log_high_risk before exit_fail. fail - The test failed and inplace upgrade is not recommended and marked as EXTERME risk. We do not recommend it.

RISK ASSESSMENT LEVELS
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 some risk that not all variants have been covered. Medium - It is likely that the area causes a problem in case of the inplace upgrade. It needs to be checked by the administrator after the inplace upgrade and after the system has been monitored for some time. High - The inplace upgrade can't be used without the administrator's assistance. This typically involves some known broken scenario, existing 3rd party packages. After the administrator manually fixes the issue, it may be possible to perform the inplace upgrade, but it is not recommended. Extreme - We found an incompatibility which makes the inplace upgrade impossible. It is recommended to install a new system with the help of preupgrade-assistant remediations. Levels None, Slight and Medium change return code exit_fail to exit_needs_inspection. Level High change exit_fail to exit_needs_action.

LOGGING
There are several functions which does logging: log_{debug,info,warning,error} <component> <message> The function create logs in format e.g: <SEVERITIES> <component> <TIMESTAMP> <MESSAGE>

INI FILE EXAMPLE
Ini file example
 [preupgrade]
 content_title: <Some title>
 content_description: <Some a pretty long description about content>
 check_script: <check script name>
 solution_file: <solution file name which advise administration in case of problems>
 author: <nauthor name with email>
 applies_to: <package name (RPM) which is test it>

AUTHORS
Petr Hracek, <phracek@redhat.com> (man page)