Configuration Scripts and Processes (Old Version)
WARNING
This page was rewritten with much better pictures presenting the different algorithms used running wpkg against packages. Feel free to read this page if you'd like, but I recommend you check out the new Configuration Scripts and Processes page instead.
Introduction
Chapter 6 - Package maintainer scripts and installation procedure
When creating a package, the project maintainer is given the option to add scripts to the package. Those scripts are run by wpkg in five different situations:
1. Validation (Validate)
As the final step of the validation process we run the validate script of each package about to be installed or removed. If any one script generates an error, it is considered that the validation process failed and the process ends there. It is VERY IMPORTANT that the validation processes do NOT change the installation target in any way other than temporary files as required. These script must simply test the validity of the installation and then exit with 1 if not considered valid for that package.
Names:
- Unix -- validate or validate.sh
- MS-Windows -- validate.bat
2. Before Installation (Preparation)
The preinst script is run before the installation occurs. This can be viewed as the final validation step of a package, although the order in which things happens, the preinst script of one package is run right before that package gets unpacked and then configured. Then the following package is dealt with. Validations, on the other hand, are all processed at once and nothing gets installed if any validation fails.
Names:
- Unix -- preinst or preinst.sh
- MS-Windows -- preinst.bat
3. After Installation (Configuration)
Once wpkg validated all packages, successfully ran the preinst script, and could unpacked all the files of a package successfully, the system runs the configuration command. This means renaming any configuration file to the official name (i.e. remove the .wpkg-new or .wpkg-user extension) and then run the postinst script.
The post installation script is also called the configuration script as it is used to dynamically finalize the configuration step of a package. When dealing with a server, this step also starts the server if it is considered safe to do so immediately. This is one of the most important feature for servers on a Unix system. This script will generally run:
service <new-service-name> start
This is quite important if you install mutliple servers at the same time and server A expects server B to already be installed and running to itself get configured (and thus started) too. Although the Pre-Depends field can be used to prevent the installation of server B at the same time as server A thus allowing you to check in your preinst script whether A is running (in the event A is not auto-started.)
Although any package can make use of a configuration script, most of the time it is primarily used by servers.
Names:
- Unix -- postinst or postinst.sh
- MS-Windows -- postinst.bat
4. Before Removal (Deconfiguration)
When wpkg is asked to remove a package, it must deconfigure it first. This is an important step because you cannot hope to delete a server from your system without first bringing it down. The prerm script is expected to be used for that purpose. Some other types of packages may also need a deconfiguration script, although it is less likely to be necessary here. If your project creates a lot of data that should also be deleted, the right place is probably the post removal script. On the other hand, if a lot of that data is considered temporary data, then it could be removed by this step to save disk space.
The removal process first calls the deconfigure command, this is where the prerm is called. You can actually just deconfigure a package with the use of the --deconfigure command line option.
Names
- Unix -- prerm or prerm.sh
- MS-Windows -- prerm.bat
5. After Removal (Cleanup)
Once wpkg deconfigured a package and removed all the files that were unpacked, it is ready to run your postrm script. This script is expected to do final cleanups. For example, if your project creates temporary files, then this script is expected to delete all those files.
You should not, however, remove files that the user created and saved for archival. You may, however, offer a user to delete those by requesting the user to chose whether to keep those files or not.
Names:
- Unix -- postrm or postrm.sh
- MS-Windows -- postrm.bat
Additional Hooks
Since version 0.9.0 wpkg offers a way to add hooks to a target. These hooks can be added using wpkg and are used by packages that wan to be notified about changes to a target (at least in term of wpkg installing, upgrading, or removing packages.)
There are two levels: hooks that run once per wpkg run (system hooks); and hooks that run once per package being handled (global hooks).
The same set of five scripts apply: validate, preinst, postinst, prerm, and postrm. The validation hooks are useful to prevent the installation of certain packages no matter what. The pre- and post- hooks are particularly useful to create signals and thus inform other applications that something is happening or just happened.
The system validation hooks are run before all the other scripts, but after the internal validation processes ran. The system pre-hooks run before all other pre-scripts. If a pre-hook fails, then the installation or removal process ends immediately.
The global validation hooks are run after the packages validation hook (for technical reasons as the list of packages is generated with that first step). Since the validation process does not modify the target system, there should be no side effects from this order.
The global pre-hooks are run before the package hooks, if they return an error, then the installation/removal do not happen. The global post-hooks are run after the package hooks. Errors returned by post-hooks are ignored (although the fact will be logged.)
To manage hooks, you can define them in your packages or use the --add-hooks, --remove-hooks, and --list-hooks command line options of wpkg.
Running Scripts and Recovery Process
When running one of the pre- or post- scripts (i.e. not the validation scripts) the packager checks the return value of the script and on an error (i.e. exit value other than 0) may decided to run additional scripts to correct the issue. Most of the processes have a recovery process run in case of error. The following diagrams show each one of those processes.
Legend:
- Black circles show the start and end point of each process.
- Green boxes include the title of the algorithm
- Orange boxes show scripts run from the new package being installed
- Blue boxes show scripts run from the old package being upgraded or removed
1. New Installation
The New Installation scripts run before the packager unpacks files from the package being installed. The preinst is run with the parameter set to install.
This case is used when the package is installed for the very first time or after a package was previously purged.
Note that if you create a package that had some problems in their Purge script (or the script was not there, somehow), then the preinst is the best place to correct such errors in this case.
As you can see, the postrm script is run as if the unpacking mechanism had failed. This allows the package maintainer to revert anything that the preinst script may have setup and should be returned back to the state it was before installation began.
2. New Installation Cancelation
When unpacking the packages, the system may encounter an error. If that happens, then the process is cancelled. First the packager removes all the files that were unpacked and then the postrm script is run with abort-install as the parameter.
3. Re-Installations
The Re-Installation algorithm is used when a package being installed was previously installed on the target system but was subsequently removed, thus only configuration files exist.
The <old-version> parameter represents the version of the currently installed package. Remember that in case of a downgrade the <old-version> is larger (newer).
In case of a server, the preinst script MUST stop the server if it is running. Failing to do so means the unpacking will fail under MS-Windows (because we cannot overwrite an executable or a DLL when in use.)
As you can see, the postrm script is run as if the unpacking mechanism had failed. This allows the package maintainer to revert anything that the preinst script may have setup and should be returned back to the state it was before installation began.
4. Re-Installations Cancellation
The Re-Installation algorithm, like the Installation, may fail while extracting files from the package. When that happens, the packager first restores the files that it has overwritten, then it deletes new files and finally it runs the postrm script with the abort-install command line option.
Note that this is the same as a brand new installation except for the specified version on the call to the script.
5. Upgrade and Downgrade Installation
The Upgrade Installation algorithm is the most advanced. As you can see, the process requires two scripts to run successfully to end with success. Any other path and the process ends in error.
The call to the preinst script is similar to a new installation, only the first command line option is upgrade instead of install.
Note that in case of an upgrade it is expected that the prerm script will stop a server if this package sets one up. The final postinst script is expected to restart the new server.
6. Upgrade and Downgrade Installation
The Finish Upgrade algorithm ends an upgrade that unpacked properly. However, this is NOT yet the end of the installation process. This is to finish up the removal of the version of the package that was just upgraded. This step cannot restart a server nor can it just delete all sorts of files since the newly upgraded package may want to use them.
The Cancel Upgrade step is presented below as it is the same as if an error occurs when the unpacking mechanism fails (actually, just the same as with an installation cancelation, only this one includes many script execution steps!)
7. Cancel Upgrade and Downgrade Installation
The Cancel Upgrade algorithm ends an upgrade by trying to restore the system back the way it was before the upgrade started.
Notice that in this case more scripts are run on Success, not on failure.
This process is used when the unpacking of the new package fails for any reason. It is also called from the pre-installation scripts when one of the scripts fails and the system decides that the state of the target needs to be restored.
8. Configure
The Configure algorithm runs the postinst script with the special option configure. It is expected to configure the server (i.e. when interactive, ask the user questions about the configuration settings) and then start the server if the package is a server.
Nothing happens to the package on failure. The system logs the failure though and you may want your script to print out information about what happened (or did not happen.)
9. Deconfigure
The Deconfigure algorithm runs the prerm script with the special commmand line option deconfigure. Note that this is not available in Debian which does not see a deconfiguration as something different from starting a full removal process.
On failure, the packager runs an abort-deconfigure in an attempt to restore the state of the target system.
10. Finish Deconfigure
The Finish Deconfigure algorithm runs the postrm script with the special commmand line option deconfigure. Note that this is not available in Debian which does not see a deconfiguration as something different from starting a full removal process.
Failures are ignored, although they will be logged.
11. Removal
The Removal algorithm runs the prerm script with the option remove. In case of a server, this script is expected to stop the server (or anything else) if one is running for that package.
DO NOT DO CLEAN UP AT THIS TIME. This has to happen in the postrm script instead, after the removal of the package has succeeded.
On failure, the packager runs an abort-remove in an attempt to restore the state of the target system as before the removal started.
12. Cancel Removal
The Cancel Removal algorithm runs the postrm script with the special option abort-remove. In case of a server, this script is expected to restart the server (or anything else) if one is running for that package.
Note that this is the same script and option that runs in the event the prerm script fails.
13. After Removal
The After Removal algorithm runs the postrm script with the option remove. In this case the script is expected to do the final cleanup for the package.
Errors returned by this script are ignored (although they are logged.) It is expecte that the clean up either cannot fail or what fails is non-important.
