Updating an Image

Use the pkg update command with no pkg-fmri specified, or with an asterisk character (*) as the pkg-fmri, to update all installed packages that have updates available to the newest version allowed by the constraints imposed on the system by installed package dependencies and publisher configuration. If non-global zones are mounted in the current image, these zones are also updated. See Updating Multiple Non-Global Zones Concurrently.

/usr/bin/pkg update [-fnvq] [-C n] [-g path_or_uri ...]
    [--accept] [--licenses] [--no-index] [--no-refresh] [--no-be-activate]
    [--no-backup-be | --require-backup-be] [--backup-be-name name]
    [--deny-new-be | --require-new-be] [--be-name name]
    [--reject pkg_fmri_pattern ...] [pkg_fmri_pattern ...]

Image Update Best Practices

Before you use the pkg update command, check the versions that are available from your configured publisher origin, and use the -nv options to display the list of packages that will be updated without actually performing the update.

If you want to update your operating system release, check the available versions of the entire incorporation package. The following command shows that Oracle Solaris 11 11/11 SRU 10 is installed, Oracle Solaris 11 11/11 SRUs 11, 12, and 13 are available, and Oracle Solaris 11.1 is available from the currently configured solaris publisher. For information about fields in the FMRI, see Fault Management Resource Identifiers.

$ pkg list -af entire
NAME (PUBLISHER)  VERSION                       IFO
entire            0.5.11,5.11-0.175.1.0.0.24.2  ---
entire            0.5.11,5.11-0.175.0.13.0.4.0  ---
entire            0.5.11,5.11-0.175.0.12.0.4.0  ---
entire            0.5.11,5.11-0.175.0.11.0.4.1  ---
entire            0.5.11,5.11-0.175.0.10.0.5.0  i--

If none of these versions is what you want, then you need to set your solaris publisher origin to a different package repository location.

By default, each package is updated from the publisher that provided the currently installed version. You can control the publisher that provides packages by specifying publisher stickiness and search order. See Adding, Modifying, or Removing Package Publishers.

The following command shows which packages, if any, would actually be installed by an update. Because the -v option is specified, this command shows the full FMRIs, including versions, of all 627 packages that would be updated, the three packages that would be removed, and the one new package that would be installed. This example omits most of that output and only shows the entire package. Because the -n option is specified, no update is actually done. Review this output before you perform an update without the -n option.

$ pfexec pkg update -nv
            Packages to remove:        3
           Packages to install:        1
            Packages to update:      627
     Estimated space available: 48.43 GB
Estimated space to be consumed:  3.14 GB
       Create boot environment:      Yes
     Activate boot environment:      Yes
Create backup boot environment:       No
          Rebuild boot archive:      Yes

Changed packages:
solaris
...
  entire
    0.5.11,5.11-0.175.0.10.0.5.0:20120803T182627Z -> 0.5.11,5.11-0.175.1.0.0.24.2:20120919T190135Z
...

The preceding example shows that the entire incorporation package for Oracle Solaris 11.1 would be installed. All installed packages that belong to the entire incorporation would be updated accordingly. Because no package FMRI was specified, any installed packages that do not belong to the entire incorporation would also be updated. All installed packages would be updated to the newest version allowed by the constraints imposed on the system by installed package dependencies and publisher configuration. Installed packages can be removed and new packages can be installed when updated installed packages specify new dependencies.

The preceding example shows that a new BE would be created for this update if you reran this command without the -n option. If you run this command without the -n option, you see the following message at the end of the update output:

A clone of currentBE exists and has been updated and activated.
On the next boot the Boot Environment newBE will be
mounted on '/'.  Reboot when ready to switch to this updated BE.

The current BE is not modified. All changes are made in the new BE.

Explicitly specifying a new BE is the safest way to install or update. See Boot Environment Policy Image Properties for information about when BEs are created. You might want to use the --be-name option to give the new BE a meaningful name. The new BE is activated, so this new environment is booted by default the next time you boot the system. If that is not what you want, use the --no-be-activate option with the pkg update command. Then when you are ready to use the new environment, use the beadm activate command to activate the new BE.

Specifying the Version to Install

If you do not want to update to the newest version allowed, you can specify the package name on the pkg update command, including a portion of the version string. The following example shows how to specify the version of the entire incorporation to update to Oracle Solaris 11 11/11 SRU 13, even though a newer version would be allowed. Be sure to use the -nv options again and check the output again.

$ pfexec pkg update -nv entire@0.5.11,5.11-0.175.0.13
            Packages to remove:        2
           Packages to install:        1
            Packages to update:      486
     Estimated space available: 48.39 GB
Estimated space to be consumed:  2.50 GB
       Create boot environment:      Yes
     Activate boot environment:      Yes
Create backup boot environment:       No
          Rebuild boot archive:      Yes

Changed packages:
solaris
...
  entire
    0.5.11,5.11-0.175.0.10.0.5.0:20120803T182627Z -> 0.5.11,5.11-0.175.0.13.0.4.0:20121106T194623Z
... 

Some installed packages might not belong to the entire incorporation. Those packages might have been installed separately and will not be updated by updating just the entire incorporation. You can add those packages to the same pkg update command.

Specifying a Version Constraint Prior to Updating

If you want to allow updates to any Oracle Solaris 11 11/11 version but not allow update to Oracle Solaris 11.1, you can freeze the entire incorporation as shown in the following command. Specifying 0.175.0 means the entire package can be updated to 0.175.0.13, for example, but not to 0.175.1.

$ pfexec pkg freeze -c "Keep this image at 11 11/11." entire@0.5.11,5.11-0.175.0
entire was frozen at 0.5.11,5.11-0.175.0
$ pkg freeze
NAME    VERSION             DATE                     COMMENT
entire  0.5.11,5.11-0.175.0 30 Jan 2013 15:50:01 PST Keep this image at 11 11/11.
$ pkg list entire
NAME (PUBLISHER)  VERSION                       IFO
entire            0.5.11,5.11-0.175.0.10.0.5.0  if-

For more information about package freezing, see Locking Packages to a Specified Version.

Constraining the Available Packages

Another way to control what versions can be installed or updated is to provide your own local IPS package repository and control that repository content. For example, your repository could contain all the support updates for Oracle Solaris 11 11/11 but not contain Oracle Solaris 11.1 packages.

If you create your own repository, be sure to update your solaris publisher origin.

For more information, see Copying and Creating Oracle Solaris 11.1 Package Repositories.

Downgrading an Image

To downgrade your operating system release, boot into a BE older than the version you want to downgrade to, and upgrade from there. For example, if you updated from Oracle Solaris 11 11/11 SRU 10 to Oracle Solaris 11 11/11 SRU 13 and then realized you need an SRU 12 image, reboot to your SRU 10 BE and update to SRU 12 from there.

More Update Command Options

When you specify the -f option when updating all installed packages, the client up-to-date check is not executed.

Use the -g option to temporarily add the specified package repository or package archive to the list of sources in the image from which to retrieve package data. See Installing a New Package for additional description and examples of the effects of the -g option.

Use the -C option to update n non-global zones concurrently with the global zone. See Updating Multiple Non-Global Zones Concurrently for an example.

Use the --accept option to indicate that you agree to and accept the terms of the licenses of the packages that are updated. If you do not provide this option, and any package licenses require acceptance, the update operation fails. Use the --licenses option to display all of the licenses for the packages that are updated as part of this operation.

When you specify the -no-refresh option, the repositories for the image's publishers are not contacted to retrieve the newest list of available packages and other metadata.

When you specify the --no-index option, the search indices are not updated after the operation has completed successfully. Specifying this option might save some time if you are installing a large number of packages. When the update operation finishes, you can use pkg refresh to update the list of available packages and publisher metadata for each publisher specified. If no publishers are specified, the refresh is performed for all publishers. If a new BE was created, do this publisher refresh in the new BE.