Preupgrade Assistant contents Packaging guidelines
How to package a Preupgrade Assistant contents
Contents files are packaged as a subpackage of main package (e.g mariadb).
Naming guidelines
Every Preupgrade Assistant content subpackage name must start with preupgrade-assistant- followed by original package name.
For example Preupgrade Assistant content subpackage for mariadb will be named preupgrade-assistant-mariadb.
Dependencies
-
All packages must have
` Requires: preupgrade-assistant`
` BuildRequires: preupgrade-assistant-devel`
Devel package contains macros and contents validating check script.
Architecture
-
All preupgrade-assistant-* subpackages must be architecture independent, i.e. have
BuildArch: noarch
.
Macros
-
Macro denoting the parent directory where the package files go is
%{preupgrade_dir}
. This currently expands to/usr/share/preupgrade
. -
Macro
%{preupg_number}
means source release from which the system is going to be upgraded, e.g. Fedora 22. -
Macro
%{postupg_number}
means target release to which the system is going to be upgraded, e.g. Fedora 23. -
Macro
%{preupg_results}
means where the contents files are generated -
Macro
%{preupgrade_name}
means Fedora%{preupg_number}_%{postupg_number}, e.g. Fedora22_23 -
Macro
%{preupgrade_dir}
reference to /usr/share/preupgrade/%{preupgrade_name}
Prep section
Copy all contents files to %{preupgrade_name}/%{name} directory.
Content files are:
-
INI file
-
check_script (python or bash)
-
text file with solution description.
INI file structure
INI file is checked by %{preupgrade_build} script. If something is missing user is informed.
[preupgrade]
content_title: Short content name
author: Your Name <yname@ydomain.com>
content_description: 'Enter your description here'
config_file:
THIS IS OPTIONAL. IT INFORMS ADMINISTRATOR WHAT FILES ARE AFFECTED
check_script: `
`solution: `
`applies_to: <specify_package_needs_to_be_on_system. if_not_installed_then_NOT_APPLICABLE> , comma separated
requires:
THIS IS OPTIONAL
The elements description:
-
content_title - Defines a single item to be checked as a part of a group.
-
author - Author of the content, will be used in automatically created header of scripts
-
content_description - Describes a rule and what the checks are.
-
config_file - Defines which configuration files are checked.
-
check_script - A script used for checking the system before upgrade. If the script does not exist, the user is notified and the group.xml autogeneration fails.
-
solution - Text file which describes how to solve a problem after an upgrade.
-
applies_to - Package checked by the script, if not available check will not run. Result is NOT_APPLICABLE.
-
requires - If a check script needs awk binary then package gawk should be mentioned here.
Bash check script template
Template for bash check script
!/bin/bash
. /usr/share/preupgrade/common.sh
#END GENERATED SECTION
This check can be used if you need root privilegues
# Copy your config file from RHEL6 (in case of scenario RHEL6_7) `
`# to Temporary Directory
CONFIG_FILE="full_path_to_your_config_file"
mkdir -p $VALUE_TMP_PREUPGRADE/cleanconf/$(dirname $CONFIG_FILE)
cp $CONFIG_FILE $VALUE_TMP_PREUPGRADE/cleanconf/$CONFIG_FILE
# Now check you configuration file for options
# and for other stuff related with configuration
# If configuration can be used on target system (like RHEL7 in case of RHEL6_7)
# the exit should be RESULT_PASS
# If configuration can not be used on target system (like RHEL 7 in case of RHEL6_7)
# scenario then result should be RESULT_FAIL. Correction of
# configuration file is provided either by solution script
# or by postupgrade script located in $VALUE_TMP_PREUPGRADE/postupgrade.d/
# if configuration file can be fixed then fix them in temporary directory
# $VALUE_TMP_PREUPGRADE/$CONFIG_FILE and result should be RESULT_FIXED
# More information about this issues should be described in solution.txt file
# as reference to KnowledgeBase article.
grep "Sometext" $CONFIG_FILE
if [ $? -ne 0 ]; then
` log_info "Config file $CONFIG_FILE will be fixed by solution script"`
` # postupgrade.d directory from your content is automatically copied by`
` # preupgrade assistant into $VALUE_TMP_PREUPGRADE/postupgrade.d/ directory`
` exit $RESULT_FAIL`
fi
exit $RESULT_PASS
Python check script template
Template for python check script
!/usr/bin/python
-- Mode: Python; python-indent: 8; indent-tabs-mode: t -- `
`import sys, os, errno
import datetime
from preup.script_api import *
END GENERATED SECTION
component = "Specify component name used for logging"
exit functions are exit_{pass,not_applicable, fixed, fail, etc.}
# logging functions are log_{error, warning, info, etc.}
# for logging in-place risk use functions log_{extreme, high, medium, slight}_risk
def main():
` if os.geteuid() != 0:`
` sys.stdout.write("Need to be root.\n")`
` log_slight_risk("The script needs to be run under root account")`
` exit_error()`
if name == "main":
` set_component(component) `
` main()`
` exit_pass()`
Build section
Run command:
%{preupgrade_build} %{preupgrade_name}/%{name}/
%{preupgrade_build} command has to succeed. Warning can be suppressed.
Install section
All files from preupgrade directory should be installed with
%install
…
mkdir -p ${buildroot}%{preupgrade_dir}/%{name}
install -p -m 755 %{SourceY} ${buildroot}%{preupgrade_dir}/%{name}/check.sh
install -p -m 644 %{SourceZ} ${buildroot}%{preupgrade_dir}/%{name}/solution.txt
install -p -m 644 %{preupgrade_name}-%{preupg_results}/%{name}/group.xml ${buildroot}%{preupgrade_dir}/%{name}/group.xml
Files section
-
Directory where Preupgrade Assistant installs files and directories must be owned by the subpackage
%files
…
%files -n preupgrade-assistant-%{name}
%dir %{preupgrade_dir}/%{name}
-
All files except text files should be listed like
%files
…
%files -n preupgrade-assistant-%{name}
%{preupgrade_dir}/%{name}/.{sh,py}
%{preupgrade_dir}/%{name}/.xml
-
All text files from content should be listed via
%files
…
%files -n preupgrade-assistant-%{name}
%doc %{preupgrade_dir}/%{name}/*.txt
Directory ownership
Directories /usr/share/preupgrade
and
%{preupgrade_dir}
are owned by package preupgrade-assistant itself and should not be owned by your package.
Sample SPEC
Name: foo Version: 1.0 Release: 1%{?dist} Summary: An example package URL: http://example.com License: MIT Source0: http://example.com/foo/foo-%{version}.tgz Source1: foo.ini Source2: foo.sh Source3: foo.txt [Bulk of foo packaging elided] %package -n preupgrade-assistant-%{name} BuildRequires: preupgrade-assistant-devel Requires: preupgrade-assistant %description -n preupgrade-assistant-%{name} Files used by preupgrade to assist with upgrading between major releases of the foo package via fedup. %prep # Copy all content files to %{preupgrade_dir} mkdir -p %{preupgrade_name}/%{name} cp %{SOURCE1} %{preupgrade_name}/%{name}/%{SOURCE1} cp %{SOURCE2} %{preupgrade_name}/%{name}/%{SOURCE2} cp %{SOURCE3} %{preupgrade_name}/%{name}/%{SOURCE3} %build %{preupgrade_build} %{preupgrade_name}/%{name}/ %install mkdir -p %{buildroot}%{preupgrade_dir}/%{name} install -p -m 755 %{SOURCE2} %{buildroot}%{preupgrade_dir}/%{name}/%{SOURCE2} install -p -m 644 %{SOURCE3} %{buildroot}%{preupgrade_dir}/%{name}/%{SOURCE3} install -p -m 644 %{preupgrade_name}-%{preupg_results}/%{name}/group.xml %{buildroot}%{preupgrade_dir}/%{name}/group.xml %files -n preupgrade-assistant-%{name} %dir %{preupgrade_dir}/%{name} %doc %{preupgrade_dir}/%{name}/*.txt %{preupgrade_dir}/%{name}/*.{py,sh} %{preupgrade_dir}/%{name}/*.xml