The following table shows similarities and differences between the pkg install and pkg update commands.
|
See the preserve and overlay attributes of the file action in the pkg(5) 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.
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.
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.
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(1M) command to show and change the active BE.
Do not create a 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.
If a backup BE is created, name it name instead of a default name. Use of --backup-be-name implies --require-backup-be.
Do not create a new BE. The install, update, uninstall, or revert operation is not performed if a new BE is required.
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.
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
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.
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.
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.
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.
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.
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.
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).
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 an Operation showed that a new BE would not be created by default when you install the group/feature/amp package. In the following partial output, a new BE is created because the --be-name option is specified:
$ pkg install -v --be-name s11amp group/feature/amp
Packages to install: 6
Mediators to change: 1
Estimated space available: 22.70 GB
Estimated space to be consumed: 751.08 MB
Create boot environment: Yes
Activate boot environment: Yes
Create backup boot environment: No
Rebuild boot archive: No
The following message displays at the end of the installation operation:
A clone of s11 exists and has been updated and activated. On the next boot the Boot Environment s11amp will be mounted on '/'. Reboot when ready to switch to this updated BE.
The pkg list command reports that the group/feature/amp package is not installed because the group/feature/amp package is not installed in the current BE. The group/feature/amp package is installed in the new s11amp BE.
$ pkg list group/feature/amp pkg list: no packages matching 'group/feature/amp' installed
Use the beadm list command to check that the system has a new active BE named s11amp. 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 Active Mountpoint Space Policy Created -- ------ ---------- ----- ------ ------- s11 N / 30.92M static 2014-03-05 08:51 s11amp R - 25.75G static 2014-03-26 10:45
Check that the group/feature/amp 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 group/feature/amp package is installed.
$ beadm mount s11amp /mnt $ beadm list BE Active Mountpoint Space Policy Created -- ------ ---------- ----- ------ ------- s11 N / 30.92M static 2014-03-05 08:51 s11amp R /mnt 25.75G static 2014-03-26 10:45 $ pkg -R /mnt list group/feature/amp NAME (PUBLISHER) VERSION IFO group/feature/amp 0.5.11-0.175.2.0.0.33.0 i--
Remember to unmount the s11amp BE.
$ beadm unmount s11amp
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
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(5) man page.
See Installing a New Package for information about publisher stickiness and search order and about using the -g option.
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 (*).
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(5) man page.
See Installing a New Package for information about using the -g option.