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:  , 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

Category:Packaging guidelines