From Grid5000

prepostinst - a postinstall script aware of prepost variables.

Contents 1 Synopsis 2 Description 3 Handled files 3.1 Ownership files 3.2 Preinstall's files 3.3 Postinstall's files 4 Performed actions 4.1 Loading variables 4.2 Transforming templates 4.3 Copying directories 4.4 Applying ownerships 4.5 Writting logs 5 Requirements 6 See also

Synopsis

prepostinst basedir

Where basedir is the location where preinstall and postinstall archives have been unpacked.

Description

prepostinst is intended to adapt a deployed system image to the current site where this image has been deployed. More than a basic postinstall's script, prepostinst is aware of prepost variables and use them to transform the generic template files it contains into site-specific files.

Technically, prepostinst performs the following action sequence:

1. Prepost's files of variables of a given version are loaded to instanciated them into memory space
2. A run report is created on destination system to log postinstall's actions
3. Preinstall's $NODE_DIR directory is copied to deployed system
4. Preinstall's $NODE_OWN ownership specification are applied to deployed system
5. Postinstall's generic template files, stored into postinstall's dest directory, are transformed into site-specific files with prepost variables values
6. Postinstall's dest directory, that now contains site-specific files, is copied to deployed system
7. Postinstall's dest.own ownership specification are applied to deployed system

Handled files

Ownership files

Some files, put inside preinstall or postinstall archives, need specific ownership on the destination filesystem. These ownerships cannot be associated to these files in the preinstall or postinstall archives, because it depends on destination filesystem. The system where postinstall's or preinstall's archives are built does not necessary know the good ownership to apply because it varies between distribution.

2 ownerships files can be used to set specific ownerships:

• $NODE_OWN sets preinstall's file ownerships
• dest.own sets postinstall's file ownerships

An ownership file contains a list of association between files and ownerships in the following syntax:

user1:group1 /path/to/file1
user2:group2 /path/to/file2

Note: a ownership specification is not recursive so it must be defined for each file of a directory.

Preinstall's files

These files describe site-specific configuration that cannot be contained in one variable. Some configurations vary a lot between sites so it has no sense to dispatch them into many variables.

For example, network configuration is not uniform between sites. Some only use eth0 whereas others use eth1 and eth2. It does not make sense to store these specificities into variables, because if we do we must have one variable per interface name and the number of interface vary between sites. So it is decided to directly copy network's configuration file to destination system.

Using preinstall's files has drawback: when he edits its postinstall, end-user does not see those preinstall's files. So, this mean must be used carefully and avoided as possible. End-user can know what preinstall's files have been copied during postinstall with postinstall's log file.

Postinstall's files

These files describe site-independent configuration template. They look like the site-specific file they represent, except that site-specific parts are replaced by prepost variable references.

For example in the /etc/fstab file, root partition is site-independently described using the following syntax:

<[ROOT_PART]>       /               <[ROOT_FSTYPE]>   errors=remount-ro  0  0

These prepost's variable references are dynamically substitued during prepostinst run by the corresponding values defined in files of variables, stored in preinstall's archive.

Using postinstall's template files is the best way to achieve site-customization on a deployed system. When end-user edits its postinstall he can adapt these template files to his own system case.

Performed actions

Loading variables

Loading variables is performed at the beginning of prepostinst run to provide access to all the prepost's variables throught script's global memory scope.

. $PREPOST_DIR/postvar-1.0.ash

A precise version of prepost's variables must be loaded, because one postinstall have to be sure all the needed variables will be there and one prepost's variables version garanties a given variable set is defined.

Transforming templates

Transforming templates is performed on postinstall's dest directory, which initially contains site-independent configuration template. For each postinstall's template file, variable references using the form <[VAR_NAME]> are collected to build a sed substitution pattern's file. Once pattern's file is ready, it is applied to template file: variable references are replaced by corresponding values so the site-independent template becomes a site-specific file.

# collect file's variable references
grep --extended-regexp --only-matching '<\[[A-Z_]+\]>' $file \
  | grep --extended-regexp --only-matching '[A-Z_]+' \
  | while read varref; do
      # fetch reference value and format it to escape newline
      varval=$(echo "$(eval echo \"\$${varref}\")" | sed -e '$!s|$|\\|')
      # build reference replacement expression
      echo "s|<\\[${varref}\\]>|$varval|"
    done >>$sedfile

# replace each reference by its corresponding value
if [ -s $sedfile ]; then
  sed -f $sedfile $file > $tmpfile
  # replace original file in a way preserving original permission
  cp $tmpfile $file
  rm $tmpfile
fi

Note: substitution pattern's file is a bit hard to create because each pattern must be expressed on a single line so newline characters must be escaped.

Copying directories

Copying directories is performed on preinstall's $NODE_DIR directory and postinstall's dest directory. It pastes site-specific Linux data tree over a site-neutral Linux data tree.

cp $CP_OPTS $srcdir/* $DEST_DIR

During copy, file permissions must be preserved but not file ownership because end-user owns its postinstall's files and these files must be owned by root on the deployed system. To garanty that, following cp options are used:

CP_OPTS='-dr --preserve=mode'

Note: to apply ownerships different than root:root, ownership files must be provided.

Applying ownerships

Applying ownerships is performed on deployed system according to preinstall's $NODE_OWN and postinstall's dest.own definitions. For each valid ownership definition contained in an ownership file, given user's and group's ownerships are applied to given file:

grep --extended-regexp --invert-match '^(#|$)' $ownfile 2>/dev/null \
  | while read own file; do \
      chroot $DEST_DIR chown $own $file; \
    done

Each ownership settings are applied inside a chroot jail that targets deployed system. This way chown thinks it is run from deployed system and then guesses UID and GID from the /etc/passwd and /etc/group files of the deployed system.

Writting logs

Writting logs is performed at the end of copying directories and applying ownerships actions to output what have been done. By default logs are output into deployed system /root/postinst.log file:

REPORT_FILE=$DEST_DIR/root/postinst.log

Note: to disable log write option, empty the REPORT_FILE variable.

Requirements

Some command line tools must be provided by deployment system for prepostinst to perform well:

ash, cat, chroot, cp, grep, ls, mkdir, rm, sed

Other commands can be indirectly required, because they are needed to load prepost's files of variables:

fdisk, ifconfig, mount

Note: prepost's variables maintainer are advised to only use above commands in their files of variables.

See also

• Current prepostinst script at InriaGforge
• Prepost online SVN repository at InriaGforge