Software Management/Code11/Scripts and Messages

From openSUSE

Code11 Update Scripts and Messages

Scripts

Purpose

Maintenance updates sometimes need additional steps to be executed outside the packages %pre and %post scripts.

Examples are any manipulations of the rpm database (which is locked during a package transaction), like running "rpm --rebuilddb"

Such scripts are a 'least resort' for any update steps which must run outside of a rpm process. It is an exceptional case and should be treated as such. For Code10, only a service pack migration required such a script.

Implementation

Update scripts are per-package.

An update script must be packaged in an RPM package following the naming convention below. This allows access to the script with 3rd party tools which usually deal only with RPMs.

[Its important to keep 'rpm only' (resp. 3rd party tools) in mind. Use of our tools (zypper, YaST) for patch&update should make things smooth and easy - but not preclude other tools, which in turn might need manual steps.]

The script is executed chroot to the target system. The script is run by bash (/bin/sh) with 'root' rights.

An RPM should package at most one such script. If multiple scripts must be run, create one 'master' script calling other scripts in the right order. In case multiple update-scripts are packaged they will be executed in arbitrary order.

libzypp ensures execution of the newly installed update scripts immediately after the transaction that installed the corresponding RPM has ended (i.e. all packages were intalled). In case the transaction is aborted by the user, scripts are not executed but logged to /var/log/zypp/history.

If the script depends on other package updates, proper 'PreRequires' for the package containing the script must be set.

There is no guarantee any shell commands (like sed, awk, etc.) or scripting languages (Perl, Python, etc.) are installed. The package containing the script must express such requirements explicitly (just like any %pre or %post script requirements).

Update scripts are installed below '/var/adm/update-scripts'.

The name of the script must be prefixed by "<name>-<version>-<release>-" of the package containing the script. This ensures scripts are non-ambiguous. See [I.4 Packaging] below on packaging tips.

Limitations

Scripts must be idempotent - running them multiple times must not have side effects.

Packaging

Update scripts must be packaged within an RPM. The script should have a proper name (remember the 'rpm only' case above) and listed as a 'Source' in the .spec file

 Source1:        testing-one-two.sh
 

Installation should copy the file into /var/adm/update-scripts and prefix it with "<name>-<version>-<release>-" of the package:

 %install
 ...
 cp %_sourcedir/testing-one-two.sh $RPM_BUILD_ROOT/var/adm/update-scripts/%{name}-%{version}-%{release}-testing-one-two.sh
 

Last step in inclusion of the script in the %files section of the .spec file:

 %files
 ...
 /var/adm/update-scripts/%{name}-%{version}.%{release}-testing-one-two.sh

[These steps should be wrapped inside RPM macros. One for the %install and one for the %files section. Negotiations with autobuild are pending ;-)]

Internals

The location where libzypp looks for update scripts is configurable via the 'update.scriptsdir' setting of /etc/zypp/zypp.conf This might be useful for debugging.

Messages

Purpose

Messages provide notifications before (pre-message) or after (post-message) a package install (resp. update)

Pre-messages are bound to updates and implemented through updateinfo.xml (TODO: link to documentation)

Post-message follow the concept outlined above for scripts.

Implementation

Messages are per-package.

A message must be packaged in an RPM package. This allows access to the message with 3rd party tools which usually deal only with RPMs.

[Its important to keep 'rpm only' (resp. 3rd party tools) in mind. Use of our tools (zypper, YaST) for patch&update should make things smooth and easy - but not preclude other tools, which in turn might need manual steps.]

An RPM should package at most one such message. If multiple messages must be displayed, distribute them across multiple packages. If multiple messages are packaged in one RPM the messages are displayed in arbitrary order.

libzypp collects all newly installed update messages immediately after the transaction that installed the corresponding RPM has ended (i.e. all packages were intalled). The collected message files are passed back to the calling application for further consumption. There is also support for an #Automated update message notification.

Messages are installed below '/var/adm/update-messages'.

The name of the message must be prefixed by "<name>-<version>-<release>-" of the package containing the message. This ensures messages are non-ambiguous. See [I.4 Packaging] below on packaging tips.

Automated update message notification

Per default libzypp passes the collected update messages to a helperscript named /usr/lib/zypp/notify-message. The script sends notification mail to 'root'.

It is also possible to turn off this behavior or to define an alternate command to be invoked as consumer of update the messages via the update.messages.notify option in /etc/zypp.conf:

##
## Command to be invoked to send update messages.
##
## Packages may leave an update message file in {update.messagesdir}.
## At the end of each commit, zypp collects those messages and may send
## a notification to the user.
##
## zypp will prepare the update messages according to the selected
## content format and pipe the content to the command.
##
## Format:
##     single - For each update message invoke the command and send
##              the message.
##     none   - For each update message invoke the command but don't
##              use a pipe to send any data. You probably want to pass
##              the message file on the commandline using %P (see
##              Substitutions).
##     digest - Single invocation of the command, sending the path
##              names of all update message. One per line.
##     bulk   - Single invocation of the command, sending the
##              concatenated content of all update messages, separated
##              by Ctrl-L.
##
## Substitutions:
##     %p     - package identification (name-version-release.arch)
##     %P     - full path to the update message file
##
## Valid values: The value is specified as "format | command".
##               An empty value will turn off any notification.
##
## Examples:     single | mail -s 'Update message from %p' root
##               none   | my-send-script -f %P
##
## Default value: single | /usr/lib/zypp/notify-message -p %p
##
# update.messages.notify = single | /usr/lib/zypp/notify-message -p %p

Limitations

(TODO) UTF-8 encoded ?

Localization ?

Packaging

Messages must be packaged within an RPM. The message should have a proper name (remember the 'rpm only' case above) and listed as a 'Source' in the .spec file

 Source1:        testing-one-two.txt
 

Installation should copy the file into /var/adm/update-messages and prefix it with "<name>-<version>-<release>-" of the package:

 %intstall
 ...
 cp %_sourcedir/testing-one-two.txt $RPM_BUILD_ROOT/var/adm/update-messages/%{name}-%{version}-%{release}-testing-one-two.txt
 

Last step in inclusion of the message in the %files section of the .spec file:

 %files
 ...
 /var/adm/update-message/%{name}-%{version}.%{release}-testing-one-two.txt

[These steps should be wrapped inside RPM macros. One for the %install and one for the %files section. Negotiations with autobuild are pending ;-)]

Internals

The location where libzypp looks for messages is configurable via the 'update.messagesdir' setting of /etc/zypp/zypp.conf This might be useful for debugging.