Internal RPM State Machines
When updating a system RPM walks through three state machines:
- TSM (Transaction State Machine)
- PSM (Package State Machine)
- FSM (File State Machine)
These state machines are chained such that the TSM enters the PSM, and the PSM enters the FSM. The TSM is responsible for the overall transaction of packages, and calls the PSM to install/erase/repackage individual packages. In turn the PSM is responsible for managing the install/erasure/repackaging of individual packages and it calls the FSM to handle the files of an individual package.
Transaction State Machine
As stated above the transaction state machine is responsible for the overall updating of the system via an rpm transaction. Each transaction (an rpmts) contains various install elements and erase elements (these are rpmte's in the source). Unlike the PSM and the FSM, the TSM does not have programatic states that it goes through (i.e. its not really coded as a state machine) but its very helpful to think of it in terms of state machine. The source files that comprise things relating to the TSM are:
- rpmte.c, rpmte.h - Defines methods and attributes of transaction elements.
- rpmts.c, rpmts.h - Defines methods and attributes of transactions.
- transaction.c - Defines high level actions that can be perfomed upon an rpmts/transaction.
Depending on how you want to think about it, you can consider the transaction state machine as having several entry points that must be manually entered (rpmtsCheck(), rpmtsOrder(), rpmtsRun()) in order, or you can think of rpmtsCheck and rpmtsOrder as just setup for the entry of the TSM via rpmtsRun(). If you take the first approach, then state machine has a high level logic of:
Check Transaction For Dependency Satisfaction (rpmtsCheck()) If success Order Transaction Elements based on dependencies (rpmtsOrder()) if success Run Transaction (rpmtsRun())
Either way you look at it the major work of the TSM is done in rpmtsRun, so below is pseudo code to document its flow:
Not Done Yet
The Package State Machine
The PSM is called at various times by the TSM for one of three purposes:
- to install a package (a transaction element from the view point of the TSM).
- to erase a package.
- to repackage a package that will be erased.
These "purposes" are seen by the PSM as an overall goal to achieve, which are defined by the following macros:
- PSM_PKGINSTALL - used to install a package.
- PSM_PKGERASE - used to erase a package.
- PSM_PKGSAVE - used to repackage a package.
The PSM is thus entered with one of these three initial states, that then gets translated to the PSM goal. Whichever the goal the PSM at a high level looks like this:
PSM_INIT # Initialize package state machine for goal if success PSM_PRE # Pre package install/erase/repackage activites (e.g. %pre) if success PSM_PROCESS # Deliver/Erase/Repackage Files (FSM is entered here). if success PSM_POST # Post package install/erase/repackage activities (e.g. %post) PSM_FINI # Clean up PSM
To enter into the PSM, a call is made to rpmpsmStage() (this is found in psm.c) with the second argument being the state/stage you wish the PSM to transition too. The intial stage is, is one of the three states listed above (i.e. PSM_PKGINSTALL, PSM_PKGERASE, PSM_PKGSTAGE). After this initial entry the PSM transitions through the five major states listed above (i.e. PSM_INIT, PSM_PRE, PSM_PROCESS, PSM_POST, PSM_FINI). Beyond these major states, their are several sub states into which each of the major states can transition. They are listed below:
- PSM_COMMIT - NOT SURE
- PSM_CHROOT_IN - Enter chroot environment.
- PSM_CHROOT_OUT - Exit chroot environment.
- PSM_SCRIPT - Run a scriptlet.
- PSM_TRIGGERS - Run triggers that are set against this package.
- PSM_IMMED_TRIGGERS - Run triggers owned by this package.
- PSM_RPMIO_FLAGS - Setup rpmio flags.
- PSM_RPMDB_LOAD - Retrieves installed package header.
- PSM_RPMDB_ADD - Adds header from package to rpmdb.
- PSM_RPMDB_REMOVE - Removes package header from rpmdb.
The following are in the PSM, but are no-ops presently (Jeff, Is there an explanation for these? Well, I know there is, but is this dead code, or code waiting to be implemented:
- PSM_PKGCOMMIT - Not used (Jeff could you elaborate on this?)
- PSM_UNDO - Not used (Jeff, ditto)
- PSM_CREATE - Not used.
- PSM_DESTROY - Not used.
- PSM_NOTIFY - Used by the PSM to notify consumers of librpm of package events.
The remaining subsections will list the high level logic of the major states (PSM_INIT, PSM_PRE, PSM_PROCESS, PSM_POST, PSM_FINI).
PSM_PKGINSTALL, PSM_PKGERASE, PSM_PKGSAVE
set PSM goal transition to PSM_INIT if OK transition to PSM_PRE if OK transition to PSM_PROCESS if OK transition to PSM_POST transition to PSM_FINI
PSM_INIT
calculate pkg instance count if goal PSM_PKGINSTALL increment pkg instance count Try to find matching NEVRAO header in rpmdb and save in PSM state. if JUSTDB return if file count is <= 0 return strip PREFIX from files in old format relocatable packages? strip / from files in current format relocatable packages if goal PSM_PKGERASE decrement pkg instance count retrieve pkg header from rpmdb if goal PSM_PKGSAVE generate path to repackaged package open repackaged package for write return
PSM_PRE
if test return transition to PSM_CHROOT_IN # This will change into the chroot, if we are not already there; then it returns here if goal PSM_PKGINSTALL # if %pre allowed setup PSM to to run %pre script transition to PSM_SCRIPT # Will run %pre script if goal PSM_PKGERASE # if %preuntrigger allowed setup PSM to run %preuntriggers transition to PSM_IMMED_TRIGGERS # runs %preuntriggers owned by this package transition to PSM_TRIGGERS # runs %preuntriggers triggered by this package # if %preun allowed setup PSM to run %preun transition to PSM_SCRIPT # runs %pre and returns here if goal PSM_PGKSAVE get package header from rpmdb transition to PSM_RPMIO_FLAGS write package lead into repackaged package write package signature into repackaged package # add REMOVETID to header write header to repackaged package
PSM_PROCESS
if test return if goal PSM_PKGINSTALL if justdb return if no files in package synthesize notify callbacks # Will result in progress hashes being printed return iterate over files in package if user of file does not exit on the system turn off SUID bit of file set user of file to 0 if group of file does not exist on the system turn off the SGID bit set group of file to 0 transition to PSM_RPMIO_FLAGS # sets compression type # if fd for package does not exist return FAILURE # if cfd for package does not exist return FAILURE enter FSM with goal of FSM_PKGINSTALL if FSM suceeded transition to PSM_COMMIT # transition to PSM_NOTIFY with RPMCALLBACK_INST_PROGRESS if FSM failed print RPM error transition to PSM_NOTIFY with RPMCALLBACK_UNPACK_ERROR return FAILURE return OK if goal PSM_PKGERASE if justdb return OK if apply only return OK # ??? if no files to erase return OK transition to PSM_NOTIFY with RPMCALLBACK_UNINST_START enter FSM with goal of FSM_PKGERASE # This will remove any files remaining owned only by this package transition to PSM_NOTIFY with RPMCALLBACK_UNINST_STOP return OK if goal PSM_PKGSAVE set fileset action to FA_COPYOUT # ??? set fileset actions to NULL if no fd for package return FAIL if no cfd for package return FAIL # ??? enter FSM with goal of FSM_PKGBUILD transition to PSM_NOTIFY with RPMCALLBACK_INST_PROGRESS return OK
PSM_POST
if test return OK if goal PSM_PKGINSTALL calculate install time set RPMTAG_FILESTATES in header # ??? set RPMTAG_INSTALLTIME in header set RPMTAG_INSTALLCOLOR in header # transition to PSM_RPMDB_REMOVE # transition to PSM_RPMDB_ADD if %post allowed transition to PSM_SCRIPT # Run %post script if %triggerin allowed transition to PSM_TRIGGERS # Run %triggerin in other packages transition to PSM_IMMED_TRIGGERS # Run %triggerin in this package if not apply only mark replaced files # ??? if goal PSM_PKGERASE if %postun allowed transition to PSM_SCRIPT # Run %postun if %triggerpostun allowed transition to PSM_TRIGGERS # Run %triggerpostun in other packages if not apply only transition to PSM_RPMDB_REMOVE # Remove header from db # transition to PSM_CHROOT_OUT return OK
PSM_FINI
# transition to PSM_CHROOT_OUT close any package fd if PSM has had error display error message transition to PSM_NOTIFY with RPMCALLBACK_CPIO_ERROR clean up
The File State Machine
NOTHING YET
Acknowledgements
This information originally came from James Olin Oden's personal examination of the rpm source code.