Assessment data format

Assessment data format

Note: This is draft version; we're in phase of collecting the requirements based on current behavior of preupgrade-assistant, its API and modules. See raw source of this file to reveal TODOs and comments.

About this document

This is specification of assessment data format. Assessment is generated by preupgrade-assistant by calling set of assessment modules which, presumably using API provided by preupgrade-assistant and performing post-processing such as creation of human-readable HTML report.

In this document, phrases MUST, MUST NOT, SHOULD and SHOULD NOT are used in meaning defined by RFC2119.

Basic structure

Assessment exists in form of a directory tree:

.
├── cleanconf
├── dirtyconf
├── hooks
├── kickstart
├── noauto_postupgrade.d
├── postmigrate.d
├── postupgrade.d
├── preupgrade-scripts
├── result.html
└── result.xml

cleanconf and dirtyconf

These directories store configuration files submitted by modules and intended to be migrated manually by system administrator.

• cleanconf - files that only need review,

• dirtyconf - files that need manual changes; context and reasoning behind such changes SHOULD be described in result.html.

Structure beneath each of these directories represents original placement of the configuration file.

Example

A module detects that /etc/libuser.conf cannot be migrated cleanly but provides "template" version that needs to be finished and deployed to destination system by system administrator. The module informs administrator about necessary changes via result.html ("solution text"). Administrator then finds the template under dirtyconf/etc/libuser.conf

hooks

This directory stores hooks submitted by modules in order to be executed at various events during the course of migration. Each hook consists of a subdirectory of hooks directory MODULE_NAME/EVENT and MUST contain at least architecture-independent program (not necessarily marked as executable) file named run_hook. Any other files or directories found here must be kept.

The run_hook script MUST be written in architecture-independent way, including proper "shebang" line.

Parent process responsible for execution of the hook MUST (in following or equivalent order):

1. Create copy of this directory.

2. Change working directory to this copy.

3. Mark run_hook as executable.

4. Execute run_hook.

   Parent process MUST NOT make any assumptions about language of run_hook.

5. Catch any output (stdout and stderr) from run_hook and represent it in its own logs in unambiguous way (ie. it must be clear from which hook (MODULE_NAME and EVENT) the output came and which was stdout and stderr.

Example

If contents of hooks is following:

hooks
└── modfoo
    └── postupgrade
        ├── dir_d1
        │   ├── file_a
        │   └── file_b
        ├── file_f1.conf
        └── run_hook

the run_hook containing following:

#!/bin/sh
echo hello
ls dir_d1/file_a
echo bye >&2

During postupgrade event, parent process will create copy of whole postupgrade directory, and run run_hook as a system executable. Parent process could log output as following:

postupgrade:modfoo:out:hello
postupgrade:modfoo:out:dir_d1/file_a
postupgrade:modfoo:err:bye

preupgrade-scripts

Directory preupgrade-scripts contains single file named release_version, purpose of which is to declare major and minor version numbers of source and destination disribution, for which the assessment is valid.

.
├── preupgrade-scripts
:   └── release_version

This file contains exactly two lines in format as follows:

<sX>.<sY>
<dX>.<dY>

where:

• <sX> and <sY> are major and minor version numbers of source disribution (i.e. where the upgrade process starts)
• and <dX> and <dY> are major and minor version numbers of destination disribution (i.e. where the upgrade process ends).

Tools performing actual upgrade or migration MUST NOT proceed unless the source disribution version matches relevant version.

Example

If assessment contains following release_version file:

6.9
7.4

the assessment is valid only for upgrade from version 6.9 to version 7.4.

Legacy hook directories

postmigrate.d and postupgrade.d serve an older implemenation of hook mechanism. Files in these directories are simply executed during the respective event.