System Administration Guide: Oracle Solaris Containers-Resource Management and Oracle Solaris Zones

Chapter 25 About Packages and Patches on a Solaris System With Zones Installed (Overview)

Solaris 10 1/06: This chapter has been completely revised.

This chapter discusses maintaining the Solaris Operating System when zones are installed. Information about adding packages and patches to the operating system in the global zone and in all installed non-global zones is provided. Information about removing packages and patches is also included. The material in this chapter supplements the existing Solaris installation and patch documentation. See the Solaris 10 Release and Installation Collection and System Administration Guide: Basic Administration for more information.

This chapter covers the following topics:

What's New in Packaging and Patching When Zones Are Installed

Solaris 10 1/06: This chapter has been rewritten since Solaris 10, to document the current behavior of the package and patch commands on a system with installed non-global zones.

Solaris 10 6/06: Information on the SUNW_PKG_ALLZONES, SUNW_PKG_HOLLOW, and SUNW_PKG_THISZONE package parameters has been revised. See Packaging and Patch Tools Overview and Package Parameter Information.

Solaris 10 6/06 and later releases: For information about how to register your system or how to use Sun Connection (formerly known as Sun Update Connection) to manage your software updates, see the Sun Connection hub on BigAdmin.

Solaris 10 8/07 and later releases:

Solaris 10 5/08 and later update releases: EOF of PatchPro. Support for PatchPro, which used the patch database and patch tools to patch software installed in global and non-global zones, ended in September 2007. For information on the current process, see Sun xVM Ops Center.

Solaris 10 5/08: Although added in the Solaris 10 5/08 release, this information is applicable to all Solaris 10 systems.

To register your Solaris system, go to https://inventory.sun.com/inventory/. For information about how to use Sun Inventory to register your hardware, software, and operating systems, see the Sun Inventory Information Center.

If you use Sun xVM Ops Center to provision, update, and manage the systems in your data center, see the Sun xVM Information Center for information about how to register your software with Sun xVM Ops Center.

Solaris 10 10/09: Zones parallel patching is an enhancement to the standard Solaris 10 patch utilities. For releases prior to Solaris 10 10/09, the patch is delivered in the patch utilities patch, 119254-66 or later revision (SPARC) and 119255-66 or later revision (x86). See Solaris 10 10/09: Zones Parallel Patching to Reduce Patching Time and Solaris 10 10/09: How to Patch Non-Global Zones in Parallel. Also see Using Update on Attach as a Patching Solution, a recommended method used to quickly update patches on a system with zones.

For a complete listing of new Solaris 10 features and a description of Solaris releases, see Oracle Solaris 10 9/10 What’s New.

Packaging and Patch Tools Overview

The Solaris packaging tools are used in administering the zones environment. The global administrator can upgrade the system to a new version of Solaris, which updates both the global and the non-global zones.

Solaris Live Upgrade, the standard Solaris interactive installation program, or the custom JumpStart installation program can be used in the global zone to upgrade a system that includes non-global zones. For a zone with the zonepath on ZFS, the following restrictions apply:

For more information, see Using Oracle Solaris Live Upgrade to Migrate or Upgrade a System With Zones (Solaris 10 10/08) in Oracle Solaris ZFS Administration Guide.

The zone administrator can use the packaging tools to administer any software installed in a non-global zone, within the limits described in this document.

The following general principles apply when zones are installed:


Note –

While certain package and patch operations are performed, a zone is temporarily locked to other operations of this type. The system might also confirm a requested operation with the administrator before proceeding.


About Packages and Zones

Only a subset of the Solaris packages installed on the global zone are completely replicated when a non-global zone is installed. For example, many packages that contain the Solaris kernel are not needed in a non-global zone. All non-global zones implicitly share the same Solaris kernel from the global zone. However, even if a package's data is not required or is not of use in a non-global zone, the knowledge that a package is installed in the global zone might be required in a non-global zone. The information allows package dependencies from the non-global zones to be properly resolved with the global zone.

Packages have parameters that control how their content is distributed and made visible on a system with non-global zones installed. The SUNW_PKG_ALLZONES, SUNW_PKG_HOLLOW, and SUNW_PKG_THISZONE package parameters define the characteristics of packages on a system with zones installed. If desired, system administrators can check these package parameter settings to verify the package's applicability when applying or removing a package in a zone environment. The pkgparam command can be used to view the values for these parameters. For more information on parameters, see Package Parameter Information. See Checking Package Parameter Settings on a System with Zones Installed for usage instructions.

For information about package characteristics and parameters, see the pkginfo(4) man page. For information about displaying package parameter values, see the pkgparam(1) man page.

Patches Generated for Packages

When a patch is generated for any package, the parameters must be set to the same values as the original package.

Interactive Packages

Any package that must be interactive, which means that it has a request script, is added to the current zone only. The package is not propagated to any other zone. If an interactive package is added to the global zone, the package is treated as though it is being added by using the pkgadd command with the -G option. For more information about this option, see About Adding Packages in Zones.

Keeping Zones in Sync

It is best to keep the software installed in the non-global zones in sync with the software installed in the global zone to the maximum extent possible. This practice minimizes the difficulty in administering a system with multiple installed zones.

To achieve this goal, the package tools enforce the following rules when adding or removing packages in the global zone.

Package Operations Possible in the Global Zone

If the package is not currently installed in the global zone and not currently installed in any non-global zone, the package can be installed:

If the package is currently installed in the global zone only:

If a package is currently installed in the global zone and currently installed in only a subset of the non-global zones:

If a package is currently installed in the global zone and currently installed in all non-global zones, the package can be removed from the global zone and from all non-global zones.

These rules ensure the following:

Package Operations Possible in a Non-Global Zone

The package operations possible in any non-global zone are:

How Zone State Affects Patch and Package Operations

The following table describes what will happen when pkgadd, pkgrm, patchadd, and patchrm commands are used on a system with non-global zones in various states.

Note that revisions to the description of the installed state have been made to the table for the Solaris 10 5/08 release.

Zone State 

Effect on Package and Patch Operations 

Configured 

Patch and package tools can be run. No software has been installed yet. 

Installed 

Patch and package tools can be run. During patch or packaging operations, the system moves a zone from the installed state to a new internal state called mounted. After patching has completed, the zone is reverted back to the installed state. 

Note that immediately after zoneadm -z zonename install has completed, the zone is also moved to the installed state. A zone in the installed state that has never been booted cannot be patched or run packaging commands. The zone must be booted to the running state at least once. After a zone has been booted at least once, and then moved back to installed state via zoneadm halt, then patch and packaging commands can be run.

Ready 

Patch and package tools can be run. 

Running 

Patch and package tools can be run. 

Incomplete 

A zone being installed or removed by zoneadm. Patch and package tools cannot be used. The tools cannot bring the zone into the appropriate state for using the tools.

About Adding Packages in Zones

The pkgadd system utility described in the pkgadd(1M) man page is used to add packages on a Solaris system with zones installed.

Using pkgadd in the Global Zone

The pkgadd utility can be used with the -G option in the global zone to add the package to the global zone only. The package is not propagated to any other zones. Note that if SUNW_PKG_THISZONE=true, you do not have to use the -G option. If SUNW_PKG_THISZONE=false, the -G option will override it.

When you run the pkgadd utility in the global zone, the following actions apply.

Adding a Package to the Global Zone and to All Non-Global Zones

To add a package to the global zone and to all non-global zones, execute the pkgadd utility in the global zone. As the global administrator, run pkgadd without the -G option.

A package can be added to the global zone and to all non-global zones without regard to the area affected by the package.

The following steps are performed by the pkgadd utility:

Adding a Package to the Global Zone Only

To add a package to the global zone only, as the global administrator in the global zone, execute the pkgadd utility with the -G option only.

A package can be added to the global zone if the following conditions are true:

The following steps are performed by the pkgadd utility:

Adding a Package Installed in the Global Zone to all Non-Global Zones

To add a package that is already installed in the global zone to all non-global zones, you must currently remove the package from the global zone and reinstall it in all zones.

These are the steps used to add a package that is already installed in the global zone to all of the non-global zones:

  1. In the global zone, use pkgrm to remove the package.

  2. Add the package without using the -G option.

Using pkgadd in a Non-Global Zone

To add a package in a specified non-global zone, execute the pkgadd utility, without options, as the zone administrator. The following conditions apply:

The following steps are performed by the pkgadd utility:

About Removing Packages in Zones

The pkgrm utility described in the pkgrm(1M) man page supports removing packages on a Solaris system with zones installed.

Using pkgrm in the Global Zone

When the pkgrm utility is used in the global zone, the following actions apply.

Note that a package can only be removed from a non-global zone by a zone administrator working in that zone if the following are true:

Removing a Package From the Global Zone and From all Non-Global Zones

To remove a package from the global zone and from all non-global zones, execute the pkgrm utility in the global zone as the global administrator.

A package can be removed from the global zone and from all non-global zones without regard to the area affected by the package.

The following steps are performed by the pkgrm utility:

Using pkgrm in a Non-Global Zone

As the zone administrator, use the pkgrm utility in a non-global zone to remove a package. The following limitations apply:

The following steps are performed by the pkgrm utility:

Package Parameter Information

Setting Package Parameters for Zones

The SUNW_PKG_ALLZONES, SUNW_PKG_HOLLOW, and SUNW_PKG_THISZONE package parameters define the characteristics of packages on a system with zones installed. These parameters must be set so that packages can be administered on a system with non-global zones installed.

The following table lists the four valid combinations for setting package parameters. If you choose setting combinations that are not listed in the following table, those settings are invalid and the package will fail to install.

Ensure that you have set all three package parameters. You can leave all three package parameters blank. The package tools interpret a missing zone package parameter as if the setting were false, but not setting the parameters is strongly discouraged. By setting all three package parameters, you specify the exact behavior the package tools should exhibit when installing or removing the package.

Table 25–1 Valid Package Parameter Settings

SUNW_PKG_ALLZONES Setting

SUNW_PKG_HOLLOW Setting

SUNW_PKG_THISZONE Setting

Package Description 

false 

false 

false 

This is the default setting for packages that do not specify values for all the zone package parameters. 

A package with these settings can be installed in either the global zone or a non-global zone.  

  • If the pkgadd command is run in the global zone, the package is installed in the global zone and in all non-global zones.

  • If the pkgadd command is run in a non-global zone, the package is installed in the non-global zone only.

In both cases, the entire contents of the package is visible in all zones where the package is installed. 

false 

false 

true 

A package with these settings can be installed in either the global zone or a non-global zone. If new non-global zones are created after the installation, the package is not propagated to these new non-global zones. 

  • If the pkgadd command is run in the global zone, the package is installed in the global zone only.

  • If the pkgadd command is run in a non-global zone, the package is installed in the non-global zone only.

In both cases, the entire contents of the package is visible in the zone where the package is installed. 

true 

false 

false 

A package with these settings can be installed in the global zone only. When the pkgadd command is run, the package is installed in the global zone and in all non-global zones. The entire contents of the package is visible in all zones.


Note –

Any attempt to install the package in a non-global zone fails.


true 

true 

false 

A package with these settings can only be installed in the global zone, by the global administrator. When the pkgadd command is run, the contents of the package is fully installed in the global zone. If a package has the package parameters set to these values, the package content itself is not delivered on any non-global zone. Only the package installation information necessary to make the package appear to be installed is installed on all non-global zones. This enables the installation of other packages to be installed that depend on this package.

For package dependency checking purposes, the package appears to be installed in all zones. 

  • In the global zone, the entire contents of the package is visible.

  • In whole root non-global zones, the entire contents of the package is not visible.

  • When a non-global zone inherits a file system from the global zone, a package installed in this file system is visible in a non-global zone. All other files delivered by the package are not visible within the non-global zone.

    For example, a sparse root non-global zone shares certain directories with the global zone. These directories are read-only. Sparse root non-global zones share the /platform file system among others. Another example is packages that deliver files relevant only to booting hardware.


Note –

Any attempt to install the package in a non-global zone fails.


SUNW_PKG_ALLZONES Package Parameter

The optional SUNW_PKG_ALLZONES package parameter describes the zone scope of a package. This parameter defines the following:

The SUNW_PKG_ALLZONES package parameter has two permissible values. These values are true and false. The default value is false. If this parameter is either not set or set to a value other than true or false, the value false is used.

The SUNW_PKG_ALLZONES parameter should be set to true for packages that must be the same package version and patch revision level across all zones. Any package that delivers functionality dependent on a particular Solaris kernel, for example, Solaris 10, should set this parameter to true. Any patch for a package must set the SUNW_PKG_ALLZONES parameter to the same value that is set in the installed package being patched. The patch revision level for any package that sets this parameter to true must be the same across all zones.

Packages that deliver functionality not dependent on a particular Solaris kernel, such as third-party packages or Sun compilers, should set this parameter to false. Any patch for a package that sets this parameter to false must also set this parameter to false. Both the package version or the patch revision level for any package that sets this parameter to false can be different between zones. For example, two non-global zones could each have a different version of a web server installed.

The SUNW_PKG_ALLZONES package parameter values are described in the following table.

Table 25–2 SUNW_PKG_ALLZONES Package Parameter Values

Value 

Description 

false

This package can be installed from the global zone to the global zone only, or to the global zone and to all non-global zones. The package can also be installed from any non-global zone to the same non-global zone. 

  • The global administrator can install the package on the global zone only.

  • The global administrator can install the package on the global zone and on all non-global zones.

  • The zone administrator can install the package on a non-global zone.

If removed from the global zone, the package is not removed from other zones. The package can be removed from individual non-global zones. 

  • The package is not required to be installed on the global zone.

  • The package is not required to be installed on any non-global zone.

  • The package is not required to be identical across all zones. Different versions of the package can exist on individual zones.

  • The package delivers software that is not implicitly shared across all zones. This means that the package is not operating system-specific. Most application-level software is in this category. Examples include the StarOffice product or a web server.

true

If installed on the global zone, this package must also be installed on all non-global zones. If removed from the global zone, the package must also be removed from all non-global zones. 

  • If the package is installed, it must be installed on the global zone. The package is then automatically installed on all non-global zones.

  • The version of the package must be identical on all zones.

  • The package delivers software that is implicitly shared across all zones. The package is dependent on the versions of software that are implicitly shared across all zones. The package should be visible in all non-global zones. Examples include kernel modules.

    These packages allow the non-global zone to resolve dependencies on packages that are installed in the global zone by requiring that the entire package be installed on all non-global zones.

  • Only the global administrator can install the package. A zone administrator cannot install the package on a non-global zone.

SUNW_PKG_HOLLOW Package Parameter

The SUNW_PKG_HOLLOW package parameter defines whether a package should be visible in any non-global zone if that package is required to be installed and be identical in all zones.

The SUNW_PKG_HOLLOW package parameter has two permissible values, true or false.

The SUNW_PKG_HOLLOW package parameter values are described in the following table.

Table 25–3 SUNW_PKG_HOLLOW Package Parameter Values

Value 

Description 

false

This is not a “hollow” package: 

  • If installed on the global zone, the package content and installation information are required on all non-global zones.

  • The package delivers software that should be visible in all non-global zones. An example is the package that delivers the truss command.

  • Other than the restrictions for the current setting of the SUNW_PKG_ALLZONES package parameter, no additional restrictions are defined.

true

This is a “hollow” package: 

  • The package content is not delivered on any non-global zone. However, the package installation information is required on all non-global zones.

  • The package delivers software that should not be visible in all non-global zones. Examples include kernel drivers and system configuration files that work only in the global zone. This setting allows the non-global zone to resolve dependencies on packages that are installed only on the global zone without actually installing the package data.

  • The package is recognized as being installed in all zones for purposes of dependency checking by other packages that rely on this package being installed.

  • This package setting includes all of the restrictions defined for setting SUNW_PKG_ALLZONES to true.

  • In the global zone, the package is recognized as having been installed, and all components of the package are installed. Directories are created, files are installed, and class action and other scripts are run as appropriate when the package is installed.

  • In a non-global zone, the package is recognized as having been installed, but no components of the package are installed. No directories are created, no files are installed, and no class action or other install scripts are run when the package is installed.

  • When the package is removed from the global zone, the system recognizes that the package was completely installed. Appropriate directories and files are removed, and class action or other install scripts are run when the package is removed.

SUNW_PKG_THISZONE Package Parameter

The SUNW_PKG_THISZONE package parameter defines whether a package must be installed in the current zone, global or non-global, only. The SUNW_PKG_THISZONE package parameter has two permissible values. These values are true and false. The default value is false.

The SUNW_PKG_THISZONE package parameter values are described in the following table.

Table 25–4 SUNW_PKG_THISZONE Package Parameter Values

Value 

Description 

false

  • If pkgadd is run in a non-global zone, the package is installed in the current zone only.

  • If pkgadd is run in the global zone, the package is installed in the global zone and also installed in all currently installed non-global zones. In addition, the package will be propagated to all future, newly installed non-global zones.

true

  • The package is installed in the current zone only.

  • If installed in the global zone, the package is not added to any currently existing or yet-to-be-created non-global zones. This is the same behavior that occurs when the -G option is specified to pkgadd.

Package Information Query

The pkginfo utility described in the pkginfo(1) man page supports querying the software package database on a Solaris system with zones installed. For information about the database, see Product Database.

The pkginfo utility can be used in the global zone to query the software package database in the global zone only. The pkginfo utility can be used in a non-global zone to query the software package database in the non-global global zone only.

About Adding Patches in Zones

In general, a patch consists of the following components:

When the patchadd command is used to apply a patch, the patch information is used to determine whether the patch is applicable to the currently running system. If determined to be not applicable, the patch is not applied. Patch dependencies are also checked against all of the zones on the system. If any required dependencies are not met, the patch is not applied. This could include the case in which a later version of the patch is already installed.

Each package contained in the patch is checked. If the package is not installed on any zone, then the package is bypassed and not patched.

If all dependencies are satisfied, all packages in the patch that are installed on any zone are used to patch the system. The package and patch databases are also updated.


Note –

Solaris 10 3/05 through Solaris 10 11/06: If a package is installed with pkgadd -G or has the pkginfo setting SUNW_PKG_THISZONE=true, the package can only be patched with patchadd -G. This restriction is removed in the Solaris 8/07 release.


Solaris 10 8/07: Deferred Activation Patching

Starting with patches 119254-41 and 119255-41, the patchadd and patchrm patch installation utilities have been modified to change the way in which certain patches delivering features are handled. This modification affects the installation of these patches on any Solaris 10 release. These deferred-activation patches better handle the large scope of change delivered in feature patches such as kernel patches associated with Solaris 10 releases after the Solaris 10 3/05 release.

Deferred-activation patching uses the loopback file system (lofs) to ensure the stability of the running system. When a patch is applied to the running system, the lofs preserves stability during the patching process. These large kernel patches have always required a reboot, but now the required reboot activates the changes made by the lofs. The patch README provides instructions on which patches require a reboot.

If you are running non-global zones or have lofs disabled, consider these points when installing or removing deferred-activation patches:


Note –

Using Solaris Live Upgrade to manage patching can prevent the problems associated with patching a running system. Solaris Live Upgrade can reduce the amount of downtime involved in patching and limit risk by providing fallback capability if problems occur. You can patch an inactive boot environment while the system is still in production, and boot back to original boot environment (BE) if problems are discovered in the new BE. See Upgrading a System With Packages or Patches in Oracle Solaris 10 9/10 Installation Guide: Solaris Live Upgrade and Upgrade Planning.


Solaris 10 10/09: Zones Parallel Patching to Reduce Patching Time

Zones parallel patching is an enhancement to the standard Solaris 10 patch utilities, which comprise the supported method for patching non-global zones on your Solaris 10 system. This feature improves zones patching performance by patching non-global zones in parallel.

For releases prior to Solaris 10 10/09, this feature is delivered in the patch utilities patch, 119254-66 or later revision (SPARC) and 119255-66 or later revision (x86).

The maximum number of non-global zones to be patched in parallel is set in a new configuration file for patchadd, /etc/patch/pdo.conf. Revision 66 or later of this patch works for all Solaris 10 systems and higher level patch automation tools such as Sun xVM Ops Center.

The global zone is still patched first. When the global zone has finished patching, the number of non-global zones set in num_proc= are patched together. The maximum number is 1.5 times the number of online CPUs , up to the number of actual non-global zones on the system.

An example is:

If there are more than this number of non-global zones on the system, the first 6 will be patched in parallel, then the remaining non-global zones will be patched as processes finish patching the first group.

Using Solaris Live Upgrade as well as the new patch to manage patching provides fallback capability if problems occur. You can patch an inactive boot environment while the system is still in production, and boot back to original boot environment (BE) if problems are discovered in the new BE.

Also see Solaris 10 10/09: How to Patch Non-Global Zones in Parallel.


Note –

To quickly update all of the packages for the zone, so that these packages match what would be seen with a newly installed non-global zone on the host, the zones can be detached while the global zone is patched, and then reattached with the -U option to match the level of the global zone. SeeUsing Update on Attach as a Patching Solution for more information.


Applying Patches on a Solaris System With Zones Installed

All patches applied at the global zone level are applied across all zones. When a non-global zone is installed, it is at the same patch level as the global zone. When the global zone is patched, all non-global zones are similarly patched. This action maintains the same patch level across all zones.

The patchadd system utility described in the patchadd(1M) man page is used to add patches on a system with zones installed.

Using patchadd in the Global Zone

To add a patch to the global zone and to all non-global zones, run patchadd as the global administrator in the global zone.

When patchadd is used in the global zone, the following conditions apply:

When you add a patch to the global zone and to all non-global zones, you do not have to consider whether the patch affects areas that are shared from the global zone.

The following steps are performed by the patchadd utility:

Using patchadd in a Non-Global Zone

When used in a non-global zone by the zone administrator, patchadd can only be used to add patches to that zone. A patch can be added to a non-global zone in the following cases:

The following steps are performed by the patchadd utility:

Interaction of patchadd -G and the pkginfo Variable on a System With Zones

The following list specifies the interaction between the -G option and the SUNW_PKG_ALLZONES variable when adding a patch in global and non-global zones.

Global zone, -G specified

If any packages have SUNW_PKG_ALLZONES=TRUE, this use results in an error and no action.

If no packages have SUNW_PKG_ALLZONES=TRUE, patch is applied to package(s) in global zone only.

Global zone, -G not specified

If any packages have SUNW_PKG_ALLZONES=TRUE, patch is applied to those package(s) in all zones.

If any packages do not have SUNW_PKG_ALLZONES=TRUE, patch is applied to those package(s) in all appropriate zones. Global zone only packages are installed only in the global zone.

Non-global zone, -G specified or not specified

If any packages have SUNW_PKG_ALLZONES=TRUE, this use results in an error and no action.

If no packages have SUNW_PKG_ALLZONES=TRUE, patch is applied to packages in non-global zone only.

Removing Patches on a Solaris System With Zones Installed

The patchrm system utility described in the patchrm(1M) man page is used to remove patches on a system with zones installed.

Using patchrm in the Global Zone

As the global administrator, you can use the patchrm utility in the global zone to remove patches. The patchrm utility cannot remove patches from the global zone only or from a subset of the non-global zones.

Using patchrm in a Non-Global Zone

As the zone administrator, you can use the patchrm utility in a non-global zone to remove patches from that non-global zone only. Patches cannot affect areas that are shared.

Product Database

Each zone's respective package, patch, and product registry database completely describes all installed software that is available on the zone. All dependency checking for installing additional software or patches is performed without accessing any other zone's database, unless a package or patch is being installed or removed on the global zone and on one or more non-global zones. In this case, the appropriate non-global zone database(s) must be accessed.

For more information about the database, see the pkgadm(1M) man page.