Go to main content

Updating Systems and Adding Software in Oracle® Solaris 11.4

Exit Print View

Updated: August 2018
 
 

Controlling Installation of Optional Components

Software can have components that are optional and components that are mutually exclusive. Examples of optional components include locales and documentation. Examples of mutually exclusive components include SPARC or x86 architecture. Optional components are called facets and mutually exclusive components are called variants.

How Facet and Variant Values Affect Package Installation

Both facets and variants are comprised of the following two components:

  • A property set on the image

  • Tags set on actions in a package manifest

Facet and variant tag values set on an action in a package manifest compared with the corresponding facet and variant property values set in the image determine whether that action can be installed.

Each facet and variant property and tag has a name and a value. A single package action can have multiple facet and variant tags.

Values of facet and variant properties and tags do not need to be set explicitly. Values can be default values or inherited values. For example, a non-global zone can inherit values from its parent global zone. Some variant property values are set in the image at initial system installation and cannot be changed.

The following algorithm describes how the facet and variant property values set on the image affect whether a particular action is installed. Values are described in more detail in the following sections.

  • An action that has no facet or variant tags in the package manifest is always installed.

  • An action that has facet tags in the package manifest is installed if the following conditions exist in the image:

    • All facet tags on the action that have a value of all have a facet property value of true in the image, either by default or by being set explicitly.

    • If any facet tag on the action has a value of true, at least one of those facet property values is also true in the image, either by default or by being set explicitly.

    In the following example, the file test.txt is installed only if both devel and optional.test are true in the image and either doc.info or doc.help is true in the image.

    file path=usr/share/doc/test.txt facet.devel=all facet.optional.test=all
    facet.doc.info=true facet.doc.help=true
  • An action with variant tags in the package manifest is installed only if the values of all the variant tags are the same as the values of the corresponding variant properties set in the image.

    In the following example, the file x86test.txt will not be installed. The following package manifest excerpt shows two variant tags set on the file x86test.txt:

    file path=usr/share/doc/x86test.txt variant.arch=i386 variant.debug.osnet=true

    The following command shows the values of these variant properties in the image:

    $ pkg variant arch debug.osnet
    VARIANT                   VALUE
    arch                      i386
    debug.osnet               false
  • An action with both facet and variant tags is installed if both the facet and the variant property values allow the action to be installed.

Showing and Changing Variant Values

Most variants have descriptive values. For example, the value of variant.arch can be i386 or sparc. The value of a variant tag on an action in a package manifest must match the value of the corresponding variant property in the image in order for that action to be installed. The arch and zone variant property values are set by the program that creates the image and installs its initial content; these values cannot be changed.

Values of variant.debug.* variants and values of unknown variants can only be true or false and are false in the image by default. An unknown variant is a variant that is introduced as a variant tag on an action in a package manifest, not known at the time the image was created.

If both debug and non-debug versions of an action are delivered, both versions must have the applicable debug variant tag explicitly set, as shown in the following example. In this example, if debug.osnet is false in the image, then the non-debug version of this file is installed; if debug.osnet is true in the image, then the debug version of this file is installed. Usually debug versions of a file also have variant.arch tags.

file payload chash=hash group=sys mode=0644 overlay=allow owner=root
path=etc/motd pkg.csize=116 pkg.size=106 preserve=true variant.debug.osnet=true
file payload chash=hash group=sys mode=0644 overlay=allow owner=root
path=etc/motd pkg.csize=70 pkg.size=50 preserve=true variant.debug.osnet=false

Use the pkg variant command to display the values of variant properties that are set in the image.

$ pkg variant
VARIANT                   VALUE
arch                      i386
opensolaris.zone          global

Use the -a option to display the values of all variants that are explicitly set in the image and all variants that are set in installed packages.

$ pkg variant -a
VARIANT                   VALUE
arch                      i386
debug.container           false
debug.osnet               false
opensolaris.zone          global

Use the -v option to display all possible variant values that can be set for installed packages.

$ pkg variant -v
VARIANT                   VALUE
arch                      i386
arch                      sparc
debug.container           false
debug.container           true
debug.osnet               false
debug.osnet               true
opensolaris.zone          global
opensolaris.zone          nonglobal

Use the pkg change-variant command to change the value of a variant property. Use the pkg variant -v command to select a value to set.


Note -  Changing variant property values might update a large number of packages and might require a new BE. Use the -nv options to review what changes will be made before you make any changes.

In the following command, a new BE would be created. See Boot Environment Policy Image Properties for information about when BEs are created. When a new BE is created, the current BE is not changed; boot to the new BE to use the debug files in this example. The -n option shows what would change if you performed the operation without -n, but the command makes no actual changes. No new BE was created in this example.

$ pkg change-variant -nv variant.debug.osnet=true
            Packages to change:       232
     Variants/Facets to change:         1
     Estimated space available: 306.74 GB
Estimated space to be consumed:   1.49 GB
       Create boot environment:       Yes
     Activate boot environment:       Yes
Create backup boot environment:        No
          Rebuild boot archive:       Yes

Changed variants/facets:
  variant debug.osnet: true

Changed packages:
solaris
  ...

Editable files to change:
  Update:
    etc/motd

Showing and Changing Facet Values

Facet properties have default values in the image and are not required to be explicitly set. Facet properties whose names begin with facet.debug or facet.optional have the value false by default. All other facet properties have the value true by default.

A facet tag on an action in a package manifest can only have the value true or all. See How Facet and Variant Values Affect Package Installation for a description and example. Actions tagged with facets whose names begin with facet.debug or facet.optional will not be installed by default. To install such actions, you must change the facet property value in the image to true. Actions tagged with any other facet will be installed by default. To avoid installing such actions, you must change the facet property value in the image to false.

Changing the value of a version-lock facet (version-lock.package-name) does not cause actions to be installed or uninstalled. Instead, version-lock facets enable or disable an incorporate type depend action. See Updating a Package Constrained by a Constraint Package.

Facet property values have one of the following three sources. These source names appear in the SRC column of pkg facet command output.

  • system – Values assigned by the system. These values usually are values of facet tags specified in system packages.

  • local – Values set by using the pkg change-facet command or by using IPS APIs.

  • parent – Values inherited from a parent image. For example, a non-global zone inherits facet settings from the global zone.

Use the pkg facet command to display the current value and source of that value of all facet properties that either have been set locally in this image or have been inherited from a parent image.

Use the pkg facet -a command to display the values of all facets that are explicitly set in the image and all facets that are set in installed packages.

The following pkg facet commands show that no doc. facet properties are set locally or inherited:

$ pkg facet doc.*
FACET                     VALUE SRC
pkg facet: no matching facets found
$ pkg facet -a doc.*
FACET                     VALUE SRC
doc.help                  True  system
doc.html                  True  system
doc.info                  True  system
doc.man                   True  system
doc.pdf                   True  system
doc.ps                    True  system

Use the pkg change-facet command to change the value of a facet property. You can set a facet property value to true, false, or none. Setting a facet property to none applies the system default value to that facet (either true or false), and the source is shown as system.


Note -  Changing facet property values might update a large number of packages and might require a new BE. Use the -nv options to review what changes will be made before you make any changes.

A facet set on the image can be a full facet such as doc.man or a pattern such as locale.*. This flexibility is useful when you want to disable a portion of the facet namespace and only enable individual facets within that namespace. For example, you could disable all locales and then only enable one or two specific locales, as shown in the following example:

$ pkg change-facet locale.*=false locale.en_US=true

In the following pkg change-facet command, a new BE was not created, but a backup BE was created. See Boot Environment Policy Image Properties for information about when BEs are created. When a backup BE is created, the original image is saved in the backup, and the current BE is changed. The original value of None under “Changed variants/facets” indicates that no local setting existed prior to this command execution; only the system settings existed, as shown by the pkg facet commands above.

$ pkg change-facet -v doc.*=false doc.man=true
            Packages to change:        97
     Variants/Facets to change:         2
            Services to change:         1
     Estimated space available: 306.34 GB
Estimated space to be consumed: 936.87 MB
       Create boot environment:        No
Create backup boot environment:       Yes
          Rebuild boot archive:        No

Changed variants/facets:
    facet doc.* (local): None -> False
    facet doc.man (local): None -> True

Changed packages:
solaris
  ...

Services:
  restart_fmri:
    svc:/application/texinfo-update:default

PHASE                                          ITEMS
...

The following pkg facet commands show the doc. facet property changes that resulted from the pkg change-facet command:

$ pkg facet doc.*
FACET                     VALUE SRC
doc.*                     False local
doc.man                   True  local
$ pkg facet -a doc.*
FACET                     VALUE SRC
doc.*                     False local
doc.help                  False local
doc.html                  False local
doc.info                  False local
doc.man                   True  local
doc.pdf                   False local
doc.ps                    False local