Go to main content

Updating Systems and Adding Software in Oracle® Solaris 11.4

Exit Print View

Updated: August 2018
 
 

Installing and Updating Packages

The following table shows similarities and differences between the pkg install and pkg update commands.

Table 2  pkg install and pkg update Comparison
pkg install
pkg update
  • Requires one or more package names as operands.

  • Installs packages that are not currently installed.

  • Updates packages that are already installed.

  • Does not downgrade packages. If you specify an installed package at a lower version, the system does not install that package.

  • Takes zero or more names of packages that are already installed as operands.

  • Updates installed packages.

  • Specifying no package names or specifying '*' updates all packages that are installed in the image.

  • Downgrades installed packages to the version specified in the FMRI.

  • Does not install packages that are not already installed. If you specify a package that is not already installed, the system does not install that package.

See the preserve and overlay attributes of the file action in the pkg(7) man page to understand how files with these attributes are handled during installation and update.

After installing or updating packages, verify installed packages. See Verifying Packages and Fixing Verification Errors.

For information about how a file action with certain attributes is treated when the package that delivers the file is installed or updated, see File Actions in Packaging and Delivering Software With the Image Packaging System in Oracle Solaris 11.4 or the pkg(7) man page.

Common Installation Options

This section discusses options that are common to multiple installation-related commands. Note that setting or unsetting a mediator, changing a variant or facet, fixing a package, or reverting a file can also involve installing, updating, or uninstalling packages.

Boot Environment Options

A new BE or a backup BE might be created automatically when you install, update, or uninstall a package. Within the constraints of the image policy regarding BEs, you can control the creation of new and backup BEs using the options described below. See Boot Environment Policy Image Properties for information about new BEs and backup BEs and how to set image policy regarding BEs.

Use the following BE options to force a new BE or backup BE to be created or not created, to give the BE a custom name, and to specify that the new BE should not be activated. These options are available for the install, exact-install, uninstall, update, revert, set-mediator, unset-mediator, change-variant, and change-facet subcommands.


Note -  Options to create a new or backup BE are ignored if the BE on which you are operating is not the currently active BE. When the BE on which you are operating is not the currently active BE, changes are made directly to that image. See the description of the -R option and the PKG_IMAGE environment variable in the pkg(1) man page.
--no-be-activate

If a BE is created, do not set it as the active BE on the next boot.

In the command output, note any messages that say a new boot environment has been created. If a new boot environment has been created and activated, that BE is booted by default on the next reboot if you do not specify the --no-be-activate option.

Use the beadm command as described in the beadm(8) man page to show and change the active BE.

--no-backup-be

Do not create a backup BE.

--require-backup-be

Create a backup BE if a new BE will not be created. Without this option, a backup BE is created based on image policy. See Boot Environment Policy Image Properties for an explanation of when backup BEs are created automatically.

--backup-be-name name

If a backup BE is created, name it name instead of a default name. Use of --backup-be-name implies --require-backup-be.

--deny-new-be

Do not create a new BE. The install, update, uninstall, or revert operation is not performed if a new BE is required.

--require-new-be

Create a new BE. Without this option, a BE is created based on image policy. See Boot Environment Policy Image Properties for an explanation of when BEs are created automatically. This option cannot be combined with --require-backup-be.

--be-name name

If a BE is created, name it name instead of a default name. Use of --be-name implies --require-new-be. Using this option is the safest way to perform operations

Options That Operate on Non-Global Zones

As discussed in Working with Non-Global Zones, only some package installations, removals, and updates performed in the global zone automatically affect non-global zones. The -r option performs the same pkg operation in non-global zones that you entered in the global zone, possibly affecting many more packages than would be affected if you did not use -r. These options are available for the install, uninstall, update, change-variant, and change-facet subcommands.

-r

Run this operation in the global zone and also in all installed solaris branded non-global zones. The effect on the non-global zone is similar to logging into each non-global zone and running the command directly.

Without this option, when you run pkg commands in the global zone, non-global zones are modified only to the extent required to keep them compatible with the global zone as described in Working with Non-Global Zones. With this option, the pkg operation is applied to all installed non-global zones except as limited by the -z and -Z options. Zones that are excluded by the -z and -Z options might still be modified if updates are required to keep them in sync with the global zone.

-z zone

Run this operation only in the specified non-global zone. The -z option can be specified multiple times. The -z option can only be used with the -r option. The -z option cannot be used with the -Z option.

-Z zone

Run this operation in all non-global zones except for the specified zone. The -Z option can be specified multiple times. The -Z option can only be used with the -r option. The -Z option cannot be used with the -z option.

The following option specifies the number of non-global zones to update concurrently with the global zone. This option is available for the install, exact-install, uninstall, update, change-variant, and change-facet subcommands.

-C n

Update at most n installed solaris branded non-global zones in parallel with the global zone. If n is 0 or a negative number, all non-global zones are updated concurrently with the global zone.

The environment variable PKG_CONCURRENCY can also be set to the value n. The -C option overrides the PKG_CONCURRENCY setting. If the -C option is specified, PKG_CONCURRENCY is ignored.

Service Action Options

A package might specify SMF service actions such as restarting or refreshing a specified service when the package is installed or updated. If you are operating on a large number of packages, the pkg operation might finish before all the service actions finish. Then you might not be able to use the newly-installed software because an associated service is not yet available.

To avoid this problem, use one of the following options to run SMF actuators synchronously with the pkg command. These options are available for the install, uninstall, update, change-variant, and change-facet subcommands.

--sync-actuators

When you specify this option, the pkg command will not return until all SMF actuators have finished in the zone in which pkg was invoked (the global zone or a non-global zone).

--sync-actuators-timeout timeout

When you specify this option, the pkg command will not return until all SMF actuators have finished or the timeout period is reached, whichever is shorter. If the actuators do not finish within the given timeout in seconds, the pkg command continues operation and exits with return code 8.

License Options

You might be required to accept a license before you can install or update a package. Use the following options to view and accept required licenses. These options are available for the install, exact-install, update, fix, change-variant, and change-facet subcommands.

--licenses

Use the --licenses option to display all of the licenses for the packages that are installed or updated as part of this operation. Licenses for all packages are displayed, not just licenses that must be accepted to enable this operation to proceed. If a license must be accepted to proceed, that license is displayed even if you do not specify the --licenses option. To view the license for a package without starting any other operation, use the pkg info command as shown in Displaying Package Licenses. To display a list of licenses that must be accepted, use the pkg contents command as shown in Displaying License Requirements.

--accept

Use the --accept option to indicate that you agree to and accept the terms of the licenses of the packages that are updated or installed. If you do not provide this option and any package licenses require acceptance, the required license is displayed and the installation operation fails.

Other Installation Options

--no-index

By default, search indexes are updated when you install, update, or uninstall packages. Use the --no-index option to not update search indexes after successful completion of these operations. Specifying this option might save some time if you are installing a large number of packages. When you are finished with all install, update, and uninstall operations, 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. This option is available for the install, exact-install, uninstall, and update subcommands.

--no-refresh

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. This option is available for the install, exact-install, and update subcommands.

Installing a New Package

By default, the newest version of a package that is compatible with the rest of the image is installed from the first publisher in the publisher search order that offers the package. To explicitly request the newest version, use latest for the version portion of the package FMRI.

If the package is already installed, the package is updated by installing the newest version of the package that is compatible with the rest of the image from the publisher that provided the currently installed version.

If more than one package is specified, and if any of the specified packages cannot be installed in this image, then none of the specified packages will be installed.

If a package is on the avoid list, installing it removes it from that list. See Avoiding Installing Some Packages in a Group Package for information about the avoid list.

Identifying and Specifying an Installable Package

If the image has more than one publisher enabled, you can control which publisher provides a package by setting publisher stickiness and search order or by specifying the publisher in the package FMRI. You can also specify the version you want to install in the package FMRI. See Fault Management Resource Identifiers for a description of a package FMRI. See Configuring Publishers for information about setting publisher stickiness and search order.

If the package name does not specify the publisher, the first publisher that provides a matching package is used as the installation source. If that publisher does not provide a version of the package that can be installed in this image, then the installation operation fails. Use the pkg list -a command to see which publishers provide a version of the package that can be installed in this image.

The following commands show that an installable version of the package atool is available from a configured publisher, but the publisher that is first in the search order has a version that is not installable in this image. See Showing Package Install State Information for information about options of the pkg list command.

$ pkg list -a atool
NAME (PUBLISHER)     VERSION    IFO
atool (isvpub)       2.0        ---
$ pkg list -af atool
NAME (PUBLISHER)     VERSION    IFO
atool                1.1        ---
atool (isvpub)       2.0        ---

In this case, the following install command fails. The packaging system finds a match of the package name atool from the publisher that is first in the search order, but that package cannot be installed.

$ pkg install atool

To install this package, make the package name more specific, as shown in the following examples:

$ pkg install //isvpub/atool
$ pkg install atool@2.0

Use the -nv option to see what will be installed before you perform the actual installation. If you receive an error message, see Troubleshooting Package Installation and Update for help.

Specifying the Source of the Package

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. Repositories that require a client SSL certificate cannot be used with this option. This option cannot be used in images that have child images (non-global zones). If non-global zones are installed in this image, use the pkg set-publisher command to add this publisher and origin. This option can be specified multiple times.

When you specify the -g option, publishers that are enabled in the image are preferred when retrieving packages.

  • If a package that matches the specified package name or package name pattern is available from a publisher that is enabled in the image, and if that same publisher is not found in the location specified by the -g option, the packaging system attempts to install the package from the publisher that is enabled in the image. After install or update, any packages provided by publishers not configured in the image are added to the image configuration without an origin.

  • If a package that matches the specified package name or package name pattern is available from a publisher that is enabled in the image, and if that same publisher publishes the package in the location specified by the -g option, the packaging system attempts to install the package from the location specified by the -g option.

In the following example, the btool package is available from the solaris publisher configured in the image. The btool package is also available from the devtool publisher with repository origin http://pkg.example1.com/ but the devtool publisher is not configured in the image. The command attempts to install the package from the solaris publisher because the publisher configured in the image is preferred to the -g source when the package is available from the configured publisher.

$ pkg install -g http://pkg.example1.com/ btool

To install the package from the devtool publisher, specify the publisher name in the package name.

$ pkg install -g http://pkg.example1.com/ //devtool/btool

In the following example, isvpub is a publisher configured in the image with an origin of /var/share/pkgrepos/isvrepo. The isvpub publisher also publishes packages to a repository at http://pkg.example2.com/ but that origin is not specified for the publisher configured in the image. The following command attempts to install the package from the http://pkg.example2.com/ location because the same publisher provides the package in both locations.

$ pkg install -g http://pkg.example2.com/ atool

See also the description of publisher stickiness in Adding, Modifying, or Removing Package Publishers.

Installing a Package Into a New Boot Environment


Tip  - 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.

The new BE is a clone of the current BE with the specified install, uninstall, or update changes applied. The current BE is not modified. The system is not automatically restarted. The new BE is the default boot selection the next time you restart the system. The current BE is still available to be booted.

If you specify the --no-be-activate option, the new BE is not the default boot selection the next time you reboot.

Use the --be-name option to force a new BE to be created or to give the new BE a meaningful name if a new BE would be created by default.

The example in Previewing Package Installation showed that a new BE would not be created by default when you install the oracle-rdbms-server-18c-preinstall package. In the following partial output, a new BE is created because the --be-name option is specified:

$ pkg install --be-name rdbms oracle-rdbms-server-18c-preinstall
           Packages to install:   4
       Create boot environment: Yes
Create backup boot environment:  No

The number of packages to install is still only four because the new BE starts as a copy of the current BE.

The following message displays at the end of the installation operation:

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

The pkg list command reports that the oracle-rdbms-server-18c-preinstall package is not installed because the oracle-rdbms-server-18c-preinstall package is not installed in the current BE. The oracle-rdbms-server-18c-preinstall package is installed in the new rdbms BE.

$ pkg list oracle-rdbms-server-18c-preinstall
pkg list: no packages matching the following patterns are installed:
  oracle-rdbms-server-18c-preinstall

Use the beadm list command to check that the system has a new active BE named rdbms. The “N” BE is currently booted. The “R” BE is the default on reboot. Use the beadm activate command to change which BE is the default on reboot.

$ beadm list
BE Name          Flags Mountpoint Space   Policy Created
---------------- ----- ---------- ------- ------ ----------------
11.4.0           N     /          221.09M static 2018-07-24 15:18
rdbms            R     -          18.93G  static 2018-08-06 12:37

Check that the oracle-rdbms-server-18c-preinstall package is installed in the new BE. Mount the new BE, and use the -R option to operate on the mounted BE. The “I” in the I column indicates that the oracle-rdbms-server-18c-preinstall package is installed.

$ beadm mount rdbms /mnt
$ beadm list
BE Name          Flags Mountpoint Space   Policy Created
---------------- ----- ---------- ------- ------ ----------------
11.4.0           N     /          221.09M static 2018-07-24 15:18
rdbms            R     /mnt       18.93G  static 2018-08-06 12:37
$ pkg -R /mnt list oracle-rdbms-server-18c-preinstall
NAME (PUBLISHER)                                             VERSION              IFO
group/prerequisite/oracle/oracle-rdbms-server-18c-preinstall 11.4-11.4.0.0.1.10.0 i--

Remember to unmount the rdbms BE.

$ beadm unmount rdbms

If you continue to work in the current BE and make changes to the image configuration, you will see reminders such as the following because the current BE is not the activated BE:

WARNING: The boot environment being modified is not the active one.  Changes
made in the active BE will not be reflected on the next boot.

Rejecting a Package

Use the --reject option of the pkg install command to prevent the specified packages from being installed. If matching packages are already installed, they are removed as part of this operation.

Rejected packages that are group dependencies are placed on the avoid list. See Avoiding Installing Some Packages in a Group Package for information about the avoid list.

The following example command installs the developer-gnu package and all of its dependencies except for the cvs dependency:

$ pkg install --reject developer/versioning/cvs group/feature/developer-gnu

Updating a Package

You can use either the install or update subcommand to update an installed package to the newest version of the package that is compatible with the rest of the image from the publisher that provided the currently installed version. To avoid unintentionally installing a package that was not already installed, use the pkg update command to update packages.

If the image has more than one publisher enabled, you can control which publisher provides a package by setting publisher stickiness and search order or by specifying the publisher in the package FMRI. You can also specify the version you want to install in the package FMRI. To explicitly request the newest version of a package, use the keyword latest for the version portion of package name. See Fault Management Resource Identifiers for a description of a package FMRI. See Configuring Publishers for information about setting publisher stickiness and search order.

Any preserved configuration files that are part of packages to be updated are installed, saved, or renamed according to the value of the preserve attribute on the file and whether the file has changed. For information about how files are preserved during package updates, see the preserve attribute in the “File Actions” section of the pkg(7) man page.

See Installing a New Package for information about publisher stickiness and search order and about using the -g option.

To be sure which versions of which packages will be installed and which files preserved, preview the operation as described in Previewing Package Installation.

If you attempt to update a package that is not currently installed, the pkg update operation exits without updating any packages. Use the --ignore-missing option to ignore packages that are not installed and prevent pkg update from failing if some packages to update are not currently installed.

See Updating or Upgrading an Oracle Solaris Image for information about the special behavior of the pkg update command when no package FMRI or pattern is specified, or if the pattern specified is an asterisk character (*).

Downgrading a Package

You can use the pkg update command to downgrade as well as upgrade packages. To downgrade a package, specify the package FMRI with a version older than the version that is currently installed. See Fault Management Resource Identifiers for a description of a package FMRI. Use the pkg list command to see which version of the package is installed and which versions are available from configured publishers.

Any preserved configuration files that are part of packages to be downgraded are installed or renamed according to the value of the preserve attribute on the file and whether the file has changed. For information about how files are preserved during package downgrades, see the preserve attribute in the “File Actions” section of the pkg(7) man page.

See Installing a New Package for information about using the -g option.

Dependencies might prevent you from downgrading a package.