Title:		postrun - delayed execution environment for procedural package scripts
Case:		PSARC/2008/078
Submitter:	Laszlo Peter
Owner:          
Timeout:	02/11/2008 

1.0 Introduction

1.1 Project/Component Working Name:

    Delayed execution environment for procedural package scripts
    
1.2 Purpose

    This project provides an easy-to-use method for calling
    commands in procedural package scripts that cannot be
    run in Live Upgrade and alternate rootdir environments
    because they are not available in older versions of Solaris
    and/or not relocatable.
    
    Patch release binding is requested.
    
2.0 Description 

    Several software projects ship with programs needed for
    updating the project's databases or caches whenever the
    configuration changes or new files/data added that invalidate
    the cache.  Examples from the GNOME world are:
     - update-mime-database
     - update-desktop-database
     - gtk-update-icon-cache
     - adding new gconf schemas to the gconf database (gconftool-2)
     - gdk-pixbuf image loaders

    On Linux, these tasks are handled by postinstall/postremove
    scripts, however that approach cannot be used on Solaris,
    because these are binary programs that won't work in Live
    Upgrade and some of them were not desiged to work properly
    in an alternate root directory (when pkgadd -R option is used)
    either.

    In these cases, the only choice is to execute the commands at the
    first system boot after installation, however, when installing
    the packages on a live system, the commands need to be executed
    immediately and no reboot is necessary.  Such behavior can
    be achieved by adding complex procedural scripts to each
    package that needs to run any of the above programs after
    installation.  This would become difficult to maintain and
    error prone, since very similar complex postinstall scripts
    would be repeated in each package. 
    An smf service would also be required, at least for each of
    the above services that takes care of the first-boot case.
    Some packages would, however, require special processing
    (e.g. adding the battery applet to the default GNOME panel
    on a laptop), such cases would need their own smf services.

    Instead, JDS in Nevada uses postrun for running these programs.
    Postrun generalizes the above idea by putting the complex
    script into a shared script (postrun itself) and using a
    single smf service for all first-boot commands.  The postrun
    script determines if it is safe to executes the commands
    in the actual installation scenario or saves it in its
    spool directory for the next system boot.  The transient
    smf service looks for spooled jobs and executes them.  When
    there are no spooled jobs, this service adds less than
    0.1 sec to the system startup time.

    This case makes postrun a Contracted Consolidation Private
    interface of GNOME so that StarOffice and other desktop
    components can also make use of it.

2.1 Interfaces

    $PKG_INSTALL_ROOT/var/lib/postrun/postrun

	script used by "root" packages (sunw_pkgtype=root)

    $BASEDIR/usr/lib/postrun

        script used by "usr" packages (sunw_pkgtype=usr)

    CLI for both of the above scripts:

    Usage: postrun [options]

    postrun reads the standard input for the commands that the
    package script requests to be executed.

    Options:
	-u, --uniq
	    If the same command is requested multiple times, the command
	    is only run once.  If it is safe to execute the command
	    immediately, it will be delayed by 5 minutes, or as set
	    using the --timeout option

	-t <n>, --timeout <n>
	    Delay the execution of uniq commands by <n> minutes.

	-b, --bg
	    Run the command in the background and return control
	    immediately

	-f <file>
	    Read the commands from <file> instead of the standard
	    input.

	-c <class>
	    Assign this job to class <class>.  Useful for querying
	    jobs with postrun-query

	-i
	    Ignore this job if it cannot be executed immediately.

	-h, -?, --help
	    Display this help

    /usr/lib/postrun-query

    Usage: postrun-query [options]

    Options:
	-c <class>, --class <class>
	    Only consider jobs the belong to class <class>

	-e, --exists
	    return 0 if spooled jobs exist 1 otherwise

	-n, --count
	    print the number of spooled jobs only.  The default
	    behaviour is to list all jobs

	-j <job>, --job <job>
	    display job number <job>

	-h, -?, --help
	    Display this help


    All interfaces Contracted Consolidation Private

3.0 Delivery

    Availability and file locations:

    +------------------+----------------------------------------------------+
    |   Package name   |                  File locations                    |
    +------------------+----------------------------------------------------+
    | SUNWpostrun-root | /var/lib/postrun/postrun                           |
    |                  | /var/lib/postrun/postrun-runq                      |
    |                  | /var/log/postrun.log                               |
    |                  | /var/spool/postrun/                                |
    +------------------+----------------------------------------------------+
    | SUNWpostrun      | /usr/lib/postrun                                   |
    |                  | /usr/lib/postrun-query                             |
    +------------------+----------------------------------------------------+

4.0 Interface Classification

     The project exports the following interfaces:

    +-----------------------------------------------------------------------+
    |                          Interfaces Exported                          |
    +------------------------------+------------------+---------------------+
    |      Interface               |  Classification  |      Comment        |
    +------------------------------+------------------+---------------------+
    | /usr/lib/postrun             |  Contracted      |                     |
    | /var/lib/postrun/postrun     |  Consolidation   |                     |
    | /usr/lib/postrun-query       |  Private         |                     |
    +------------------------------+------------------+---------------------+
    | SUNWpostrun                  |  Uncommitted     |                     |
    | SUNWpostrun-root             |  Uncommitted     |                     |
    +------------------------------+------------------+---------------------+
    | svc:/system/postrun          |  Uncommitted     | transient service   |
    |                              |                  | for executing       |
    |                              |                  | spooled jobs        |
    +------------------------------+------------------+---------------------+