Go to main content

Updating Systems and Adding Software in Oracle® Solaris 11.4

Exit Print View

Updated: August 2018
 
 

Configuring Image and Publisher Properties

To implement image policies, set image properties. This section describes image and publisher properties and how to set these properties. See also "Image Properties" in the pkg(1) man page for descriptions of image properties.

Daemons or other programs that need to know the time an image was last modified can consult the time stamp on the file /var/pkg/modified. The time stamp on /var/pkg/modified is updated every time an operation occurs that modifies the image. Use the pkg history command to display information about the change at that time. See Viewing Operation History for more information.

Boot Environment Policy Image Properties

An image is a location where IPS packages can be installed and where other IPS operations can be performed. A boot environment (BE) is a bootable instance of an image. You can maintain multiple BEs on your system, and each BE can have different software versions installed. When you boot your system, you have the option to boot into any of the BEs on the system.

A new BE can be created automatically as a result of package operations. You can also explicitly create a new BE. Whether a new BE is created depends on image policy, as discussed in this section.

By default, a new BE is automatically created when you perform one of the following operations:

  • Install or update particular key system packages such as some drivers and other kernel components. Key system components can be updated when you change a variant or facet as well as when you install, uninstall, and update packages.

  • Specify any of the following options: --be-name, --require-new-be, --backup-be-name, --require-backup-be.

  • Set the be-policy image policy to always-new. Under this policy, all package operations are performed in a new BE set as active on the next boot.

When a new BE is created, the system performs the following steps:

  1. Creates a clone of the current BE.

    The clone BE includes everything hierarchically under the main root dataset of the original BE. Shared file systems are not under the root dataset and are not cloned. Instead, the new BE accesses the original shared file systems.

  2. Updates the packages in the clone BE. Does not update any packages in the current BE.

    If non-global zones are configured in the current BE, these existing zones are configured in the new BE.

  3. Sets the new BE as the default boot choice the next time the system is booted unless --no-be-activate is specified. The current BE remains as an alternate boot choice.

When a backup BE is created, the system performs the following steps:

  1. Creates a clone of the current BE.

  2. Updates the packages in the current BE. Does not update any packages in the clone BE.

If a new BE is required but not enough space is available to create it, you might be able to delete existing unneeded BEs. For more information about BEs, see Creating and Administering Oracle Solaris 11.4 Boot Environments.

See Setting Image Properties for information about how to set the following image properties.

be-policy

Specifies when a BE is created during packaging operations. The following values are allowed:

default

Apply the default BE creation policy: create-backup.

always-new

Require a reboot for all package operations by performing them in a new BE set as active on the next boot. A backup BE is not created unless explicitly requested.

This policy is the safest, but is more strict than most sites need because no packages can be added without a reboot.

create-backup

For package operations that require a reboot, this policy creates a new BE that is set as active on the next boot. If packages are modified or content that could affect the kernel is installed and the operation affects the live BE, a backup BE is created but not set as active. A backup BE can also be explicitly requested.

This policy is potentially risky only if newly installed software causes system instability, which is possible, but relatively rare.

when-required

For package operations that require a reboot, this policy creates a new BE set as active on the next boot. A backup BE is not created unless explicitly requested.

This policy carries the greatest risk because if a packaging change to the live BE makes further changes impossible, a recent fallback BE might not exist.

Properties for Signing Packages

If you are installing signed packages, set the image properties and publisher properties described in this section to verify package signatures.

Image Properties for Signed Packages

Configure the following image properties to use signed packages.

signature-policy

The value of this property determines the checks that will be performed on manifests when installing, updating, modifying, or verifying packages in the image. The final policy applied to a package depends on the combination of image policy and publisher policy. The combination will be at least as strict as the stricter of the two policies taken individually. By default, the package client does not check whether certificates have been revoked. To enable those checks, which might require the package client to contact external web sites, set the check-certificate-revocation image property to true. The following values are allowed:

ignore

Ignore signatures for all manifests.

verify

Verify that all manifests with signatures are validly signed but do not require all installed packages to be signed.

This is the default value.

require-signatures

Require that all newly installed packages have at least one valid signature. The pkg fix and pkg verify commands also warn if an installed package does not have a valid signature.

require-names

Follow the same requirements as require-signatures but also require that the strings listed in the signature-required-names image property appear as a common name of the certificates used to verify the chains of trust of the signatures.

signature-required-names

The value of this property is a list of names that must be seen as common names of certificates while validating the signatures of a package.

Publisher Properties for Signed Packages

Configure the following publisher properties to use signed packages from a particular publisher.

signature-policy

The function of this property is identical to the function of the signature-policy image property except that this property applies only to packages from the specified publisher.

signature-required-names

The function of this property is identical to the function of the signature-required-names image property except that this property applies only to packages from the specified publisher.

Configuring Package Signature Properties

Use the set-property, add-property-value, remove-property-value, and unset-property subcommands to configure package signature properties.

Use the --set-property, --add-property-value, --remove-property-value, and --unset-property options of the set-publisher subcommand to specify signature policy and required names for a particular publisher.

The following example configures this image to require all packages to be signed. This example also requires the string "oracle.com" to be seen as a common name for one of the certificates in the chain of trust.

$ pkg set-property signature-policy require-names oracle.com

The following example configures this image to require all signed packages to be verified.

$ pkg set-property signature-policy verify

The following example configures this image to require that all packages installed from the publisher example.com must be signed.

$ pkg set-publisher --set-property signature-policy=require-signatures example.com

The following example adds a required signature name. This example adds the string trustedname to the image's list of common names that must be seen in a signature's chain of trust to be considered valid.

$ pkg add-property-value signature-required-names trustedname

The following example removes a required signature name. This example removes the string trustedname from the image's list of common names that must be seen in a signature's chain of trust to be considered valid.

$ pkg remove-property-value signature-required-names trustedname

The following example adds a required signature name for a specified publisher. This example adds the string trustedname to the example.com publisher's list of common names that must be seen in a signature's chain of trust to be considered valid.

$ pkg set-publisher --add-property-value \
signature-required-names=trustedname example.com

Additional Image Properties

ca-path

Specifies a path name that points to a directory where CA certificates are kept for SSL operations. The format of this directory is specific to the underlying SSL implementation. To use an alternate location for trusted CA certificates, change this value to point to a different directory. See the CApath portions of SSL_CTX_load_verify_locations(3openssl) for requirements for the CA directory.

The default value is /etc/openssl/certs.

check-certificate-revocation

If set to true, the package client attempts to contact any CRL distribution points in the certificates used for signature verification to determine whether the certificate has been revoked since being issued.

The default value is False.

content-update-policy

Specify when the package system will update non-editable files during packaging operations. The following values are allowed:

default

Always apply the default content update policy.

always

Always download and update non-editable files that have changed.

when-required

Download and update non-editable files that have changed only if the package system has determined that an update is required.

The default value is always.

flush-content-cache-on-success

If set to true, the package client removes the files in its content-cache when image-modifying operations complete successfully. For operations that create a BE, the content is removed from both the source and destination BE.

This property can be used to keep the content-cache small on systems with limited disk space. This property can cause operations to take longer to complete.

The default value is True.

mirror-discovery

This property tells the package client to discover link-local content mirrors using mDNS and DNS-SD. If this property is set to true, the package client attempts to download package content from mirrors it dynamically discovers. To run a mirror that advertises its content via mDNS, see the pkg.depotd(8) man page.

The default value is False.

send-uuid

Send the Universally Unique Identifier (UUID) for this image when performing network operations. Although users can disable this option, some network repositories might refuse to talk to package clients that do not supply a UUID.

The default value is True.

trust-anchor-directory

The value of this property is the path name of the directory that contains the trust anchors for the image. This path is relative to the root of the image.

The default value is etc/certs/CA.

use-system-repo

This property indicates whether the image should use the system repository as a source for image and publisher configuration and as a proxy for communicating with the publishers provided. See the pkg.sysrepo(8) man page for information about system repositories.

The default value is ignore.

Setting Image Properties

Use the pkg property command to view image property settings. Use the set-property, add-property-value, remove-property-value, and unset-property subcommands to configure image properties.

Displaying the Values of Image Properties

Use the pkg property command to view the properties of an image.

$ pkg property
PROPERTY                       VALUE
be-policy                      default
ca-path                        /etc/openssl/certs
check-certificate-revocation   False
flush-content-cache-on-success False
mirror-discovery               False
preferred-authority            solaris
publisher-search-order         ['solaris', 'isvpub']
send-uuid                      True
signature-policy               verify
signature-required-names       []
trust-anchor-directory         etc/certs/CA
use-system-repo                False

You might want to use the search order options of the pkg set-publisher command to set the publisher-search-order property. See Setting Publisher Search Order and Stickiness.

Setting the Value of an Image Property

Use the pkg set-property command to set the value of an image property or add and set a property.

The following example sets the value of the mirror-discovery property.

$ pkg set-property mirror-discovery true
$ pkg property -H mirror-discovery
mirror-discovery True

Resetting the Value of an Image Property

Use the pkg unset-property command to reset the values of the specified properties to their default values.

$ pkg unset-property mirror-discovery
$ pkg property -H mirror-discovery
mirror-discovery False