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.

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 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:

• Update particular key system packages such as some drivers and other kernel components. This can happen when you install, uninstall, update, change variant, or change facet.

  Often a new BE is created when you execute the pkg update command to update all packages that have updates available.

• 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, but 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.

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

See Setting Image Properties for instructions to set the image properties described below.

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 since no packages can be added without a reboot.

create-backup

For package operations that require a reboot, this policy creates a new BE 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 since 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 what checks 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 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 only applies 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 only applies 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 for this image.

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.

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

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

$ pfexec 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.

$ pfexec 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.

$ pfexec pkg add-property-value signature-require-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.

$ pfexec pkg remove-property-value signature-require-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.

$ pfexec pkg set-publisher --add-property-value \
signature-require-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 this is 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.

flush-content-cache-on-success

If this is set to True, the package client removes the files in its content-cache when install or update operations complete. For update operations, the content is removed only from the source BE. When a packaging operation next occurs in the destination BE, the package client flushes its content cache if this option has not been changed.

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 client to discover link-local content mirrors using mDNS and DNS-SD. If this property is set to True, the client attempts to download package content from mirrors it dynamically discovers. To run a mirror that advertises its content via mDNS, see pkg.depotd(1M).

The default value is False.

send-uuid

Send the image's Universally Unique Identifier (UUID) when performing network operations. Although users can disable this option, some network repositories might refuse to talk to 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 image.

The default value is ignore.

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 pkg.sysrepo(1M) for information about system repositories.

The default value is ignore.

Setting Image Properties

Use the set-property, add-property-value, remove-property-value, and unset-property subcommands to configure properties for this image.

/usr/bin/pkg property [-H] [propname ...]
/usr/bin/pkg set-property propname propvalue
/usr/bin/pkg add-property-value propname propvalue
/usr/bin/pkg remove-property-value propname propvalue
/usr/bin/pkg unset-property propname ...

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

The preferred-authority and publisher-search-order properties can be set using pkg set-publisher command options. See Adding, Modifying, or Removing Package Publishers.

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.

$ pfexec 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.

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