How Package Changes Are Performed

The following steps are executed when pkg is invoked to modify the software installed on the machine:

• Check the input for errors

• Determine the system end-state

• Run basic checks

• Run the solver

• Optimize the solver results

• Evaluate actions

• Download content

• Execute actions

• Process actuators

When executing these steps in the global zone, pkg can also operate on any non-global zones on the system. For example, pkg ensures that dependencies are correct between the global zone and non-global zones, and downloads content and executes actions as needed for non-global zones. Chapter 10, Handling Non-Global Zones discusses zones in detail.

Check Input for Errors

Basic error checking is performed on the options presented on the command line.

Determine the System End State

A description of the desired end state of the system is constructed. In the case of updating all packages in the image, the desired end state might be something like “all the packages currently installed, or newer versions of them.” In the case of package removal, the desired end state is “all the packages currently installed without this one.”

IPS attempts to determine what the user intends this end state to look like. In some cases, IPS might determine an end state that is not what the user intended, even though that end state does match what the user requested.

When troubleshooting, it is best to be as specific as possible. The following command is not specific:

# pkg update

If this command fails with a message such as “No updates available for this image,” then you might want to try a more specific command such as the following command:

# pkg update "*@latest"

This command defines the end state more precisely, and can produce more directed error messages.

Run Basic Checks

The desired end state of the system is reviewed to make sure that a solution is possible. During this basic review, pkg checks that a plausible version exists of all dependencies, and that desired packages do not exclude each other.

If an obvious error exists, then pkg prints an appropriate error message and exits.

Run the Solver

The solver forms the core of the computation engine used by pkg(5) to determine the packages that can be installed, updated, or removed, given the constraints in the image and constraints introduced by any new packages for installation.

This problem is an example of a Boolean satisfiability problem, and can be solved by a SAT solver.

The various possible choices for all the packages are assigned Boolean variables, and all the dependencies between those packages, any required packages, and so on, are cast as Boolean expressions in conjunctive normal form.

The set of expressions generated is passed to MiniSAT. If MiniSAT cannot find any solution, the error handling code attempts to walk the set of installed packages and the attempted operation and print the reasons that each possible choice was eliminated.

If the currently installed set of packages meets the requirements but no other set does, pkg reports that there is nothing to do.

As mentioned previously, the error message generation and specificity is determined by the inputs to pkg. Being as specific as possible in commands issued to pkg produces the most useful error messages.

If MiniSAT finds a possible solution, the optimization phase begins.

Optimize the Solver Results

The optimization phase is necessary because there is no way to describe some solutions as more desirable than others to a SAT solver. Instead, once a solution is found, IPS adds constraints to the problem to separate less desirable choices, and to separate the current solution as well. IPS then repeatedly invokes MiniSAT and repeats the above operation until no more solutions are found. The last successful solution is taken as the best one.

The difficulty of finding a solution is proportional to the number of possible solutions. Being more specific about the desired result produces solutions more quickly.

Once the set of package FMRIs that best satisfy the posed problem is found, the evaluation phase begins.

Evaluate Actions

In the evaluation phase, IPS compares the packages currently installed on the system with the end state, and compares package manifests of old and new packages to determine three lists:

• Actions that are being removed.

• Actions that are being added.

• Actions that are being updated.

The action lists are then updated in the following ways:

• Directory and link actions are reference counted, and mediated link processing is done.

• Hard links are marked for repair if their target file is updated. This is done because updating a target of a hard link in a manner that is safe for currently executing processes breaks the hard links.

• Editable files moving between packages are correctly handled so that any user edits are not lost.

• Action lists are sorted so that removals, additions, and updates occur in the correct order.

All currently installed packages are then cross-checked to make sure that no packages conflict. Example conflicts include two packages that deliver a file to the same location, or two packages that deliver the same directory with different directory attributes.

If conflicts exist, the conflicts are reported and pkg exits with an error message.

Finally, the action lists are scanned to determine whether any SMF services need to be restarted if this operation is performed, whether this change can be applied to a running system, whether the boot archive needs to be rebuilt, and whether the amount of space required is available.

Download Content

If pkg is running without the -n flag, processing continues to the download phase.

For each action that requires content, IPS downloads any required files by hash and caches them. This step can take some time if the amount of content to be retrieved is large.

Once downloading is complete, if the change is to be applied to a live system (the image is rooted at /), and a reboot is required, the running system is cloned and the target image is switched to the clone.

Execute Actions

Executing actions involves actually performing the install or remove methods specific to each action type on the image.

Execution begins with all the removal actions being executed. If any unexpected content is found in directories being removed from the system, that content is placed in /var/pkg/lost+found.

Execution then proceeds to install and update actions. Note that all the actions have been blended across all packages. Thus all the changes in a single package operation are applied to the system at once rather than package by package. This permits packages to depend on each other and exchange content safely. For details on how files are updated, see File Actions.

Process Actuators

If the changes are being applied to a live system, any pending actuators are executed at this point. These are typically SMF service restarts and refreshes. Once these are launched, IPS updates the local search indices. Actuators are discussed in detail in Chapter 7, Automating System Change as Part of Package Installation.

Update Boot Archive

If necessary, the boot archive is updated.