This explanation is intended to show how maintainer scripts work, in a more graphical manner than the one explained in the Debian Policy. It's not intended as a replacement, but as a clarification.

For that purpose, this is going to be illustrated with several diagrams (made with dia). In the figures, the maintainer scripts called and their params are showed inside boxes, the possible outcomes ("OK" or "FAILED") lead to different consequences. External actions to the maintainer scripts are showed in italics, while the package ending status is showed in bold.

Installation

Let's start with the most simple example: the installation of a new package, one that wasn't installed first.

Let's explain this figure a little bit: when a package is being installed, first preinst install is called, then postinst configure. If all goes well, then the status of the package is Installed.

But, if something in the preinst install fails, then postrm abort-install is called. If this goes ok, the user will get an error message, and the package will be left in a Not Installed state. But if the postrm abort-install also fails, the package will be left in a nasty state: Half Installed, Reinst required. This means that the package needs to be reinstalled even if you want to remove it.

If something in the postinst configure fails, then the user is shown an error message, and the package is left in Failed-Config state.

The rest of the figures follow the same pattern, the explanations will be less verbose from now on.

Removal

When removing a package that was previously installed, if everything goes well, the package will be left in the Config Files state, this means that it needs to be purged before it is in the Not installed state.

If something goes wrong at the postrm stage, and the postinst abort-remove script is called, then the package might be left in a strange state: it is still Installed, but the files are not there anymore. If any of the processes fails, when the package removal is tried again, it will resume from where it left (i.e. if the prerm worked and the postrm didn't, it'll resume from the postrm).

Purging

If a package that is in state Config Files has to be purged, the cycle is really simple: the conffiles are deleted and then postrm purge is called. If it fails, the package is left in the same state, although the conffiles have already been deleted and the deletion won't be attempted again.

Removing and Purging

If the package is to be removed and purged at the same time, both diagrams combine, forming a diagram in which the package passes to be Not installed if everything goes ok.

Note that there's no way that the package might end-up in a Config files state, even if "postrm purge" fails.

Installing from '''Config-Files''' state

If a package was installed and then removed, but not purged, it's left in Config-Files state. If the installation of a new version is attempted at that moment, the order of the scripts will be almost the same as the simple installation ones, but with a slight difference: the scripts receive a second parameter indicating the old version that used to be present.

The other difference is that if postrm abort-install is called, the package is left in the same state that was before the install was attempted (i.e Config-Files).

Upgrading

The next step in complexity (and it's a big step) is doing an install that is actually upgrading an already installed package.

As you can see from the diagram, if all goes well four scripts are called, but when things go wrong, it gets much more complicated, and the package might be left in many different states.

Conflicting packages

The only thing left that is in the Policy and not in the previous diagram is when a package is being replaced by one that conflicts with it. I won't deal with it now and here, but if you are willing to do the tests and the diagrams yourself, you are free to edit this page and include them.

Sources for the diagrams

The diagrams used in this page were made with dia, and are available for download at: http://www.marga.com.ar/~marga/debian/diagrams/, all this documentation is GPL and you can make use of it for whatever you like.