Go to main content

man pages section 7: Standards, Environments, Macros, Character Sets, and Miscellany

Exit Print View

Updated: Wednesday, August 8, 2018
 
 

pkg(7)

Name

pkg - Image Packaging System

Description

The image packaging system, pkg(7), is a framework that provides for software lifecycle management (installation, upgrade, and removal). Image packaging manages software in units of packages, which are collections of actions, defined by a set of key/value pairs and possibly a data payload. In many cases, actions are files found in a file system, but they also represent other installable objects, such as drivers, services, and users.

Package FMRIs and Versions

Each package is represented by a fault management resource identifier (FMRI) with the scheme pkg:. The full FMRI for a package consists of the scheme, a publisher, the package name, and a version string in the following format:

pkg://solaris/system/library/c++-runtime@11.4-11.4.0.0.1.1.2:20170919T184404Z

solaris is the publisher. system/library/c++-runtime is the package name. Although the namespace is hierarchical and arbitrarily deep, there is no enforced containment; the name is arbitrary. The publisher information is optional, but must be preceded by pkg:// if present. An FMRI that includes the publisher is often referred to as being “fully qualified.” If publisher information is not present, then the package name should generally be preceded by pkg:/.

Packaging clients often allow the scheme of an FMRI to be omitted if it does not contain publisher information. For example, pkg:/system/library/c++-runtime can be written as system/library/c++-runtime. If the scheme is omitted, clients also allow omission of all but the last component of a package name for matching purposes. For example, system/library/c++-runtime could be written as library/c++-runtime or c++-runtime, which would then match packages named c++-runtime or package names ending in /c++-runtime.

A publisher name identifies a person, group of persons, or an organization as the source of one or more packages. To avoid publisher name collisions and help identify the publisher, a best practice is to use a domain name that represents the entity publishing the packages as a publisher name.

The version follows the package name, separated by an at (@) sign. The version consists of a component version, a branch version, and a timestamp. The component version and branch version are separated by a hyphen (-). The branch version and timestamp are separated by a colon (:). Leading zeros (for example, 01.1 or 1.01) are not permitted in elements of the component version or branch version. Trailing zeros (for example, 1.10) are permitted.

Component version: 11.4. For components tightly bound to the operating system, the component version number is minor.update. Components with their own development lifecycle, such as FOSS components, have their own version numbers, such as 2.4.10. The component version can be arbitrarily long.

Branch version: 11.4.0.0.1.1.2. The branch version, if present, must follow a hyphen (-). The branch version string is the same as the “Branch” in pkg info output.

Oracle Solaris packages show the following information in the branch version portion of the version string of a package FMRI:

minor.update.sru.order.platform.build.rev
Minor release number: 11

The minor portion of major.minor that is output by the uname -r.

Update release number: 4

The update release number for this Oracle Solaris release.

SRU number: 0

The Support Repository Update (SRU) number for this update release. SRUs are approximately monthly updates that fix bugs, fix security issues, or provide support for new hardware. The Oracle Support Repository is available only to systems under a support contract.

Order: 0

This value is used internally.

Platform: 1

This value is used internally.

Release or SRU build number: 1

The build number of the SRU, or the respin number for the release.

Revision or nightly build number: 2

The build number for the individual nightly builds.

If the package is an Interim Diagnostic or Relief (IDR) update, then the branch version of the package FMRI contains the following two additional fields. IDRs are package updates that help diagnose customer issues or provide temporary relief for a problem until a formal package update is issued. The following examples are for idr824, which has FMRI pkg://solaris/idr824@4,5.11:20131114T034951Z and contains packages such as pkg://solaris/system/library@11.4-11.4.0.0.1.1.2.824.4:

IDR: 824

The name of the IDR.

IDR ID: 4

The version of the IDR.

Timestamp: 20170919T184404Z. The timestamp must follow a colon (:). The timestamp is the time the package was published in ISO-8601 basic format: YYYYMMDDTHHMMSSZ.

When performing comparisons between versions, no component of the full version is considered unless the components to its left are the same. Thus, 4.3-1 is greater than 4.2-7 because 4.3 is greater than 4.2, and 4.3-3 is greater than 4.3-1 because 3 is greater than 1.

The pkg.human-version attribute can be used to provide a human-readable version string. The value of the pkg.human-version attribute can be provided in addition to the package version described above for the package FMRI but cannot replace the package FMRI version. The human-readable version string is only used for display purposes. See “Set Actions” for more information.

Many parts of the system, when appropriate, abridge FMRIs when displaying them, and accept input in shorter forms to reduce the volume of information displayed or required. Typically, the scheme, publisher, build version, and timestamp can be elided. Sometimes all of the versioning information can be omitted.

Actions

Actions represent the installable objects on a system. Actions are described in the manifest of a package.

To remove a file or other installable object from the image, remove the associated action from the package manifest. The object will be removed from the image when the package is updated by using the pkg update command. For more information, see Packaging and Delivering Software With the Image Packaging System in Oracle Solaris 11.4.

Every action consists primarily of its name and a key attribute. Together, these refer to a unique object as it follows a version history. Actions can have other attributes. Some attributes are interpreted directly by the packaging system. Other attributes might be useful only to the system administrator or the end-user.

Actions have a simple text representation:

action_name attribute1=value1 attribute2=value2 ...

Names of attributes cannot have whitespace, quotation marks, or equals signs (=) in them. All characters after the first equals sign belong to the value. Values can have all of those, though spaces must be enclosed in single or double quotation marks. Single quotation marks do not need to be escaped inside a string that is enclosed in double quotation marks, and double quotation marks do not need to be escaped inside a string that is enclosed in single quotation marks. A quotation mark can be prefixed with a backslash (\) character to avoid terminating the quoted string. A backslash can be escaped with a backslash.

Actions can have multiple attributes. Some attributes can be named multiple times with different values for a single action. Multiple attributes with the same name are treated as unordered lists.

Actions with many attributes can create long lines in a manifest file. Such lines can be wrapped by terminating each incomplete line with a backslash. Note that this continuation character must occur between attribute/value pairs. Neither attributes nor their values nor the combination can be split.

The attributes listed below are not an exhaustive set. In fact, the attributes that can be attached to an action are arbitrary, and the standard sets of attributes are easy to augment to incorporate future developments.

Some attributes cause additional operations to be executed outside of the packaging context. These attributes are documented in the “Actuators” section below.

Actions that are installed to a path must not deliver content to any of the following paths:

/system/volatile
/tmp
/var/share
/var/tmp

Additionallly, the following directories are reserved for use by the system and should also not be used by actions:

/var/pkg

File Actions

The file action represents an ordinary file. The file action references a payload, and has four standard attributes:

path

The file system path where the file is installed. This is a file action's key attribute.

mode

The access permissions (in numeric form) of the file. These are simple permissions only, not ACLs.

owner

The name of the user that owns the file.

group

The name of the group that owns the file.

The payload is a positional attribute in that it is not named. It is the first word after the action name. In a published manifest, it is the SHA-1 hash of the file contents. If present in a manifest that has yet to be published, it represents the path where the payload can be found. See pkgsend(1). The hash attribute can be used instead of the positional attribute, should the value include an equals sign. Both can be used in the same action. However, the hashes must be identical.

The preserve and overlay attributes affect whether and how a file action is installed.

preserve

Specifies when and how files are preserved during package operations.

When a package is initially installed, if a file delivered by the package has a preserve attribute defined with any value except abandon or install-only and the file already exists in the image, the existing file is stored in /var/pkg/lost+found and the packaged file is installed.

When a package is initially installed, if a file delivered by the package has a preserve attribute defined and the file does not already exist in the image, whether that file is installed depends on the value of the preserve attribute:

  • If the value of preserve is abandon or legacy, the packaged file is not installed.

  • If the value of preserve is not abandon or legacy, the packaged file is installed.

When a package is downgraded, if a file delivered by the downgraded version of the package has a preserve attribute defined with any value except abandon or install-only and all of the following conditions are true, the file that currently exists in the image is renamed with the extension .update, and the file from the downgraded package is installed.

  • The file exists in the image.

  • The content of the file delivered by the downgraded version of the package is different from the content of the file delivered by the currently installed version of the package.

  • The content of the file delivered by the downgraded version of the package is different from the content of the file that exists in the image.

If any of the above conditions is not true, the file is treated the same as if the package is being upgraded, rather than downgraded.

When a package is upgraded, if a file action delivered by the upgraded version of the package has a preserve attribute defined with any value and the file action is the same as the file action delivered by the currently installed version of the package, the file is not installed, and the file that exists in the image is not modified. Any modifications made since the previous version was installed are preserved.

When a package is upgraded, if a file action delivered by the upgraded version of the package has a preserve attribute defined and the file action is new or is different from the file action delivered by the currently installed version of the package, the upgrade is done in the following way:

  • If the file delivered by the upgraded version of the package has a preserve value of abandon or install-only in the upgraded package, the new file will not be installed and the existing file will not be modified.

  • If the file does not exist in the image, the new file is installed.

  • If the file delivered by the upgraded version of the package exists in the image, did not exist in the currently installed version of the package, and was not renamed or moved by using the original_name attribute (see below), then the existing file is stored in /var/pkg/lost+found and the file delivered by the upgraded version of the package is installed.

  • If the file delivered by the upgraded version of the package exists in the image and has different content from the file delivered by the currently installed version of the package, the upgrade is done according to the value of the preserve attribute:

    • If the file delivered by the upgraded version of the package has a preserve value of renameold, the existing file is renamed with the extension .old, and the new file is installed with updated permissions and timestamp (if present). See the timestamp attribute description below.

    • If the file delivered by the upgraded version of the package has a preserve value of renamenew, the new file is installed with the extension .new and the existing file is not modified.

    • If the file delivered by the upgraded version of the package has a preserve value of true, the new file is not installed, but the permissions and timestamp (if present) are reset on the existing file.

  • If the file delivered by the upgraded version of the package exists in the image, has the same content as the file delivered by the currently installed version of the package, and has a preserve value of either renameold or renamenew, the existing file is replaced by the file delivered by the upgraded version of the package, including replacing permissions and timestamp (if present).

  • If the file delivered by the upgraded version of the package exists in the image, has a preserve value of legacy in the upgraded package, and has a different preserve value in the currently installed version of the package, the existing file is renamed with the extension .legacy, and the new file is installed with updated permissions and timestamp (if present).

  • If the file delivered by the upgraded version of the package exists in the image and has a preserve value of legacy in both the upgraded package and the currently installed version of the package, the permissions and timestamp (if present) are reset on the existing file.

Unless otherwise specified above, when a package is downgraded or upgraded, any file action previously delivered by a package that is not listed in the new package version is removed from the system. Additionally, when the package is uninstalled, any file action delivered by the package is removed.

When a package is uninstalled, if a file action delivered by the currently installed version of the package has a preserve value of abandon and the file exists in the image, the file is not removed. However, any other file action delivered by that package that is removed, that has a preserve attribute specified, and that has been modified since it was originally installed is moved to /var/pkg/lost+found.

overlay

Specifies whether the action allows other packages to deliver a file at the same location or whether it delivers a file intended to overlay another file. This functionality is intended for use with configuration files that do not participate in any self-assembly (for example, /etc/motd) and that can be safely overwritten.

If overlay is not specified, multiple packages cannot deliver files to the same location.

The overlay attribute can have one of the following values:

allow

One other package is allowed to deliver a file to the same location. This value has no effect unless the preserve attribute is also set.

true

The file delivered by the action overwrites any other action that has specified allow.

Changes to the installed file are preserved based on the value of the preserve attribute of the overlaying file. On removal, the contents of the file are preserved if the action being overlaid is still installed, regardless of whether the preserve attribute was specified. Only one action can overlay another, and the mode, owner , and group attributes must match.

overlay-attributes

Specifies whether image-modifying operations such as install, update, etc. should report errors when an overlaying action has a different owner, group, mode or sysattr from its overlaid action. overlay-attributes is usually used in actions with overlay equal to allow or deny. When the value of overlay-attributes for either overlaying action or overlaid action is deny, an error will be generated during image-modifying operations. Also verification operations will generate an error on those mismatched attributes: owner, group and mode if overlay is equal to deny for a pair of overlaid and overlaying action. Otherwise, an info message will be generated on the above mismatched attributes for the pair. Regardless of the value of overlay-attributes, mismatched attributes when comparing the on-disk attributes of a file to its packaged version will always be reported as errors.

dehydrate

Specifies whether this action should be removed when a package publisher's packages are dehydrated or when a dehydrated publisher's packages are modified. The value of the dehydrate attribute can be true or false. If the value of the dehydrate attribute is false, the action will not be removed during dehydrate operations. Otherwise, the action will be removed. File actions tagged with the preserve or overlay attributes are implicitly excluded from dehydration operations and do not need this attribute.

file path=etc/zones/SYSdefault.xml dehydrate=false ...

The following attributes are recognized for ELF files:

elfarch

The architecture of the ELF file. This is the output of uname -p on the architecture for which the file is built.

elfbits

This is 32 or 64.

elfhash

This is the hash of the “interesting” ELF sections in the file. These are the sections that are mapped into memory when the binary is loaded. These are the only sections necessary to consider when determining whether the executable behavior of two binaries will differ.

The following additional attributes are recognized for file actions:

original_name

This attribute is used to handle editable files moving from package to package or from place to place, or both. The form this takes is the name of the originating package, followed by a colon and the original path to the file. Any file being deleted is recorded either with its package and path, or with the value of the original_name attribute if specified. Any editable file being installed that has the original_name attribute set uses the file of that name if it is deleted as part of the same packaging operation.

release-note

This attribute is used to indicate that this file contains release note text. The value of this attribute is a package FMRI. If the FMRI specifies a package name that is present in the original image and a version that is newer than the version of the package in the original image, this file will be part of the release notes. A special FMRI of feature/pkg/self refers to the containing package. If the version of feature/pkg/self is 0, this file will only be part of the release notes on initial installation.

revert-tag

This attribute is used to tag editable files that should be reverted as a set. The value of the revert-tag attribute is a tagname. Multiple revert-tag attributes can be specified for a single file action. The file reverts to its manifest-defined state when pkg revert is invoked with any of those tags specified. See the pkg(1) man page for information about the pkg revert command.

The revert-tag attribute can also be specified at the directory level. See “Directory Actions” below.

sysattr

This attribute is used to specify any system attributes that should be set for this file. The value of the sysattr attribute can be a comma-separated list of verbose system attributes or a string sequence of compact system attribute options, as shown in the following examples. Supported system attributes are explained in the chmod(1) man page. System attributes specified in the manifest are set additionally to system attributes that might have been set by other subsystems of the operating system.

file path=opt/secret_file sysattr=hidden,sensitive
file path=opt/secret_file sysattr=HT
timestamp

This attribute is used to set the access and modification time on the file. The timestamp attribute value must be expressed in UTC in ISO-8601 format, omitting the colons and hyphens.

The timestamp attribute is essential when packaging .pyc or .pyo files for Python. The related .py file for the .pyc or .pyo files must be marked with the timestamp embedded within those files, as shown in the following example:

file path=usr/lib/python2.7/vendor-packages/pkg/__init__.pyc ...
file path=usr/lib/python2.7/vendor-packages/pkg/__init__.py \
     timestamp=20130311T221521Z ...

The following attributes for file actions are automatically generated by the system and should not be specified by package developers:

hash

The SHA-1 hash of the uncompressed file.

chash

The SHA-1 hash of the compressed file.

pkg.size

The size in bytes of the uncompressed file.

pkg.csize

The size in bytes of the compressed file.

Directory Actions

The dir action is like the file action in that it represents a file system object. The dir action represents a directory instead of an ordinary file. The dir action has the same path, mode, owner, and group attributes that the file action has, and path is the key attribute. The dir action also accepts the revert-tag attribute. The value of the revert-tag attribute is different for file and dir actions.

Directories are reference counted in IPS. When the last package that either explicitly or implicitly references a directory no longer does so, that directory is removed. If that directory contains unpackaged file system objects, those items are moved into $IMAGE_META/lost+found. See the “Files” section for more information about $IMAGE_META.

revert-tag

This attribute is used to identify unpackaged files that should be removed as a set. See “File Actions” above for a description of how to specify this attribute for file actions. For directories, the value of the revert-tag attribute is tagname=pattern. Multiple revert-tag attributes can be specified for a single dir action. When pkg revert is invoked with a matching tagname, any unpackaged files or directories under this dir directory that match pattern (using shell globbing characters) are removed. See the pkg(1) man page for information about the pkg revert command.

salvage-from

This attribute can be used to move unpackaged contents into a new directory. The value of this attribute is the name of a directory of salvaged items. A directory with a salvage-from attribute inherits on creation any contents of the directory named in the value of the salvage-from attribute.

Link Actions

The link action represents a symbolic link. The link action has the following standard attributes:

path

The file system path where the symbolic link is installed. This is a link action's key attribute.

target

The target of the symbolic link. The file system object to which the link resolves.

mediator

Specifies the entry in the mediation namespace shared by all path names participating in a given mediation group (for example, python ). Link mediation can be performed based on mediator-version and/or mediator-implementation. All mediated links for a given path name must specify the same mediator. However, not all mediator versions and implementations need to provide a link at a given path. If a mediation does not provide a link, then the link is removed when that mediation is selected. A mediator , in combination with a specific version and/or implementation represents a mediation that can be selected for use by the packaging system.

mediator-version

Specifies the version (expressed as a dot-separated sequence of nonnegative integers) of the interface described by the mediator attribute. This attribute is required if mediator is specified and mediator-implementation is not. A local system administrator can set the version to use explicitly. The value specified should generally match the version of the package delivering the link (for example, runtime/python-27 should use mediator-version=2.7), although this is not required.

mediator-implementation

Specifies the implementation of the mediator for use in addition to or instead of the mediator-version. Implementation strings are not considered to be ordered and a string is arbitrary selected by pkg (7) if not explicitly specified by a system administrator.

The value can be a string of arbitrary length composed of alphanumeric characters and spaces. If the implementation itself can be versioned or is versioned, then the version should be specified at the end of the string, after an at (@) sign (expressed as a dot-separated sequence of nonnegative integers). If multiple versions of an implementation exist, the default behavior is to select the implementation with the greatest version.

If only one instance of an implementation mediation link at a particular path is installed on a system, then that one is chosen automatically. If future links at the path are installed, the link is not switched unless a vendor, site, or local override applies, or if one of the links is version mediated.

mediator-priority

When resolving conflicts in mediated links, pkg(7) normally chooses the link with the greatest value of mediator-version or based on mediator-implementation if that is not possible. This attribute is used to specify an override for the normal conflict resolution process.

If this attribute is not specified, the default mediator selection logic is applied.

If the value is vendor, the link is preferred over those that do not have a mediator-priority specified.

If the value is site, the link is preferred over those that have a value of vendor or that do not have a mediator-priority specified.

A local system administrator can override the selection logic described above.

Hardlink Actions

The hardlink action represents a hard link. It has the same attributes as the link action, and path is also its key attribute.

Driver Actions

The driver action represents a device driver. The driver action does not reference a payload. The driver files themselves must be installed as file actions. The following attributes are recognized (see add_drv(8) for more information):

name

The name of the driver. This is usually, but not always, the file name of the driver binary. This is the driver action's key attribute.

alias

This represents an alias for the driver. A given driver can have more than one alias attribute. No special quoting rules are necessary.

class

This represents a driver class. A given driver can have more than one class attribute.

perms

This represents the file system permissions for the driver's device nodes.

clone_perms

This represents the file system permissions for the clone driver's minor nodes for this driver.

policy

This specifies additional security policy for the device. A given driver can have more than one policy attribute, but no minor device specification can be present in more than one attribute.

privs

This specifies privileges used by the driver. A given driver can have more than one privs attribute.

devlink

This specifies an entry in /etc/devlink.tab. The value is the exact line to go into the file, with tabs denoted by \t. See devlinks(8) for more information. A given driver can have more than one devlink attribute.

Depend Actions

The depend action represents an inter-package dependency. A package can depend on another package because the first requires functionality in the second for the functionality in the first to work, or even to install. Dependencies can be optional. If a dependency is not met at the time of installation, the packaging system attempts to install or update the dependent package to a sufficiently new version, subject to other constraints.

The following attributes are recognized:

fmri

The FMRI representing the dependent package. This is the dependency action's key attribute. The fmri value must not include the publisher. The package name is assumed to be complete. Dependencies of type group-any and require-any can have multiple fmri attributes. A version is optional on the fmri value, though for some types of dependencies, an fmri with no version has no meaning or the version is ignored.

type

The type of the dependency.

require

The dependency is required and must have a version equal to or greater than the version specified in the fmri attribute. If the version is not specified, any version satisfies the dependency. A package cannot be installed if any of its required dependencies cannot be satisfied.

optional

The dependency, if present, must be at the specified version level or greater.

exclude

The containing package cannot be installed if the dependency is present at the specified version level or greater. If no version is specified, the dependent package cannot be installed concurrently with the package specifying the dependency.

incorporate

The dependency is optional, but the version of the dependent package is constrained. See “Constraints and Freezing” below.

require-any

Any one of the packages specified by multiple fmri attributes can satisfy the dependency, following the same rules as the require dependency type.

conditional

The dependency is required only if the package defined by the predicate attribute is present on the system.

origin

Prior to installation of this package, the dependency target must, if installed, be at the specified value or greater in the image to be modified. If the value of the root-image attribute is true, this applies to the image mounted at / instead.

If the value of the root-image attribute is true and the value of the fmri attribute starts with pkg:/feature/firmware/, the remainder of the fmri value is treated as a command in /usr/lib/fwenum that evaluates the firmware dependency. See Packaging and Delivering Software With the Image Packaging System in Oracle Solaris 11.4 for examples.

group

The dependency is required unless the package is on the image avoid list. Note that obsolete packages silently satisfy the group dependency. See the avoid subcommand in pkg(1).

group-any

Any one of multiple dependent packages as specified by multiple fmri attributes can satisfy the dependency, following the same rules as the group dependency type with the exception that non-obsolete package stems are preferred over obsolete ones.

parent

The dependency is ignored if the image is not a child image. If the image is a child image then the dependency is required to be present in the parent image. The package version matching for a parent dependency is the same as that used for incorporate dependencies.

predicate

The FMRI representing the predicate for conditional dependencies.

root-image

Has an effect only for origin dependencies as mentioned above.

License Actions

The license action represents a license or other informational file associated with the package contents. A package can deliver licenses, disclaimers, or other guidance to the package installer through the use of the license action.

The payload of the license action is delivered into the image metadata directory related to the package, and should only contain human-readable text data. It should not contain HTML or any other form of markup. Through attributes, license actions can indicate to clients that the related payload must be displayed and/or require acceptance of it. The method of display and/or acceptance is at the discretion of clients.

The following attributes are recognized:

license

This is a license action's key attribute. This attribute provides a meaningful description for the license to assist users in determining the contents without reading the license text itself. Some example values include:

  • ABC Co. Copyright Notice

  • ABC Co. Custom License

  • Common Development and Distribution License 1.0 (CDDL)

  • GNU General Public License 2.0 (GPL)

  • GNU General Public License 2.0 (GPL) Only

  • MIT License

  • Mozilla Public License 1.1 (MPL)

  • Simplified BSD License

The license value must be unique within a package. Including the version of the license in the description, as shown in several of the examples above, is recommended. If a package has code under multiple licenses, use multiple license actions. The length of the license attribute value should not be more than 64 characters.

must-accept

When true, this license must be accepted by a user before the related package can be installed or updated. Omission of this attribute is equivalent to false. The method of acceptance (interactive or configuration-based, for example) is at the discretion of clients. For package updates, this attribute is ignored if the license action or payload has not changed.

must-display

When true, the action's payload must be displayed by clients during packaging operations. Omission of this value is equivalent to false. This attribute should not be used for copyright notices. This attribute should only be used for licenses or other material that must be displayed during operations. The method of display is at the discretion of clients. For package updates, this attribute is ignored if the license action or payload has not changed.

Legacy Actions

The legacy action represents package data used by a legacy packaging system. The attributes associated with this action are added into the legacy system's databases so that the tools querying those databases can operate as if the legacy package were actually installed. In particular, this should be sufficient to convince the legacy system that the package named by the pkg attribute is installed on the system, so that the package can be used to satisfy dependencies.

The following attributes, named in accordance with the parameters on pkginfo(4), are recognized:

category

The value for the CATEGORY parameter. The default value is system.

desc

The value for the DESC parameter.

hotline

The value for the HOTLINE parameter.

name

The value for the NAME parameter. The default value is none provided.

pkg

The abbreviation for the package being installed. The default value is the name from the FMRI of the package. This is a legacy action's key attribute.

vendor

The value for the VENDOR parameter.

version

The value for the VERSION parameter. The default value is the version from the FMRI of the package.

Set Actions

The set action represents a package-level attribute, or metadata, such as the package description.

The following attributes are recognized:

name

The name of the attribute.

value

The value given to the attribute.

The set action can deliver any metadata the package author chooses. However, there are a number of well defined attribute names that have specific meaning to the packaging system.

info.classification

One or more tokens that a pkg(7) client can use to classify the package. The value should have a scheme (such as “org.opensolaris.category.2008” or “org.acm.class.1998”) and the actual classification, such as “Applications/Games”, separated by a colon (:).

pkg.description

A detailed description of the contents and functionality of the package, typically a paragraph or so in length.

pkg.fmri

The name and version of the containing package. See “Package FMRIs and Versions” in the “Description” section.

pkg.human-version

The version scheme used by IPS is strict. See “Package FMRIs and Versions” in the “Description” section. A more flexible version can be provided as the value of the pkg.human-version attribute. The value is displayed by IPS tools such as pkg info, pkg contents, and pkg search. The pkg.human-version value is not used as a basis for version comparison and cannot be used in place of the pkg.fmri version.

pkg.obsolete

When true, the package is marked obsolete. An obsolete package can have no actions other than more set actions, and must not be marked renamed.

pkg.renamed

When true, the package has been renamed. There must be one or more depend actions in the package as well that point to the package versions to which this package has been renamed. A package cannot be marked both renamed and obsolete, but otherwise can have any number of set actions.

pkg.summary

A short, one-line description of the package.

Group Actions

The group action defines a UNIX group as defined in group(4). No support is present for group passwords. Groups defined with this action initially have no user list. Users can be added with the user action. The following attributes are recognized:

groupname

The value for the name of the group.

gid

The group's unique numerical id. The default value is the first free group under 100.

User Actions

The user action defines a UNIX user as defined in /etc/passwd, /etc/shadow, /etc/group, and /etc/ftpd/ftpusers files. Entries are added to the appropriate files for users defined with this user action.

The user action is intended to define a user for a daemon or other software to use. Do not use the user action to define administrative or interactive accounts.

The following attributes are recognized:

username

The unique name of the user

password

The encrypted password of the user. Default value is *LK* . See shadow(4).

uid

The unique uid of the user. Default value is first free value under 100.

group

The name of the user's primary group. Must be found in /etc/group.

gcos-field

The value of the gcos field in /etc/passwd . Default value is username.

home-dir

The user's home directory. This directory must be in the system image directories and not under another mount point such as /home. Default value is /.

login-shell

The user's default shell. Default value is empty.

group-list

Secondary groups to which the user belongs. See group(4).

ftpuser

Can be set to true or false. The default value of true indicates that the user is permitted to login via FTP. See ftpusers(4).

lastchg

The number of days between January 1, 1970, and the date that the password was last modified. Default value is empty. See shadow(4).

min

The minimum number of days required between password changes. This field must be set to 0 or above to enable password aging. Default value is empty. See shadow(4).

max

The maximum number of days the password is valid. Default value is empty. See shadow(4).

warn

The number of days before password expires that the user is warned. See shadow(4).

inactive

The number of days of inactivity allowed for that user. This is counted on a per-machine basis. The information about the last login is taken from the machine's lastlog file. See shadow(4).

expire

An absolute date expressed as the number of days since the UNIX Epoch (January 1, 1970). When this number is reached, the login can no longer be used. For example, an expire value of 13514 specifies a login expiration of January 1, 2007. See shadow(4).

flag

Set to empty. See shadow(4).

Actuators

In certain contexts, additional operations can be appropriate to execute in preparation for or following the introduction of a particular action. These additional operations are operating system specific and are generally needed only on a live system image. A live image is the image mounted at / of the active, running boot environment of the current zone. When multiple actions involved in a package installation or removal have identical actuators, then the operation corresponding to actuator presence is executed once for that installation or removal.

Incorrectly specified actuators can result in package installation failure if the actuator cannot determine a means of making safe installation progress.

The following actuators are defined:

reboot-needed

Can be set to true or false. This actuator declares that update or removal of the tagged action must be performed in a new boot environment if the package system is operating on a live image. Creation of a new boot environment is controlled by the be-policy image property. See the “Image Properties” section in the pkg(1) man page for more information about the be-policy property.

disable_fmri, refresh_fmri, restart_fmri, suspend_fmri

Each of these actuators takes the value of an FMRI of a service instance to operate on during the installation or removal of the package. Fully specify the service instance to avoid ambiguity.

With disable_fmri, refresh_fmri, and restart_fmri, the FMRI value can contain a pattern that matches multiple service instances. The pattern to match must be specified explicitly with a glob that is accepted by the svcs command, rather than implicitly by not indicating any instances.

If the same service FMRI is tagged by multiple actions, possibly in multiple packages, the operation specified by that actuator is performed only once. For example, if multiple restart_fmri actuators specify the same FMRI, that service is restarted only one time for that pkg operation.

The following list of SMF actuators describes the effect on the service FMRI that is the value of each named actuator. In these descriptions, “uninstalling the package” also includes moving the file action that delivers the service to a different package.

disable_fmri

Disable (svcadm disable) the specified service prior to uninstalling the package.

refresh_fmri

Refresh (svcadm refresh) the specified service after installing, updating, or uninstalling the package.

restart_fmri

Restart (svcadm restart) the specified service after installing, updating, or uninstalling the package.

suspend_fmri

Temporarily disable (svcadm disable -t) the specified service prior to updating the package, and then enable (svcadm enable) the service after updating the package. The specified service value must be a fully specified service instance FMRI (for example, svc:/site/mysvc:default instead of svc:/site/mysvc) and cannot include globbing characters. suspend_fmri can be performed only on services that are enabled and applies only to package update operations.

SMF actuators are not executed in the following cases:

  • When operating on an alternate root (pkg -R /path/to/BE).

  • When recursing from the global zone (pkg subcommand -r).

Mediations

A mediator is a name that represents a set of related symbolic or hard links. If two or more link actions have the same path and mediator name, the user or the package system selects the link target based on version, implementation, or priority. See “Link Actions” for information about mediator attributes.

The following example shows two different instances of a mediator named java where the link choices are between versions. These two link actions would appear in two different packages.

link mediator=java mediator-version=1.6 path=usr/java target=jdk/jdk1.6.0_31
link mediator=java mediator-version=1.7 path=usr/java target=jdk/jdk1.7.0_02

See the set-mediator subcommand in the pkg(1) man page for information about how to select the version you want for this link path. To have a choice of versions, both packages must be installed.

Constraints and Freezing

When a package is transitioned to a new version, or when it is added to or removed from the system, the version that is chosen, or whether removal is allowed, is determined by a variety of constraints put on the package. Those constraints can be defined by other packages in the form of dependencies, or by the administrator in the form of freezes.

The most common form of constraint is delivered by the require dependency, as described in “Depend Actions” above. Such a constraint prevents the package from being downgraded or removed.

Most parts of the operating system are encapsulated by packages called incorporations. These packages primarily deliver constraints represented by the incorporate dependency.

As described above, an incorporated package need not be present on the system, but if it is, then it specifies both an inclusive minimum version and an exclusive maximum version. For example, if the dependent FMRI has a version of 1.4.3, then no version less than 1.4.3 would satisfy the dependency, and neither would any version greater than or equal to 1.4.4. However, versions that merely extended the dotted sequence, such as 1.4.3.7, would be allowed.

Incorporations are used to force parts of the system to upgrade synchronously. For some components, such as the C library and the kernel, this is a basic requirement. For others, such as a simple userland component on which nothing else has a dependency, the synchronous upgrade is used merely to provide a known and tested set of package versions that can be referred to by a particular version of the incorporation.

Since an incorporation is simply a package, it can be removed, and all the constraints it delivers are therefore relaxed. However, many of the incorporations delivered by Oracle Solaris are required by the packages they incorporate because that relaxation would not be safe.

Attempting an upgrade of a package to a version that is not allowed by an installed incorporation will not attempt to find a newer version of the incorporation in order to satisfy the request, but will instead fail. If the constraint itself must be moved, and the incorporation specifying it cannot be removed, then the incorporation must be upgraded to a version that specifies a desired version of the constraint. Upgrading an incorporation causes all of the incorporated packages that would not satisfy the constraints delivered by the new version to be upgraded as well.

A system administrator can constrain a package by using the pkg freeze command. The named package is constrained to the version installed on the system if no version is provided. If a versioned package is provided, then this administrative constraint, or freeze, acts as if an incorporate dependency were installed where the fmri attribute had the value of the provided package version.

A freeze is never lifted automatically by the packaging system. To relax a constraint, use the pkg unfreeze command.

Publishers and Repositories

As detailed above, a publisher is simply a name that package clients use to identify the provider of packages. Publishers can distribute their packages using package repositories and/or package archives. There are two types of repositories currently supported by the package system: origin repositories and mirror repositories.

An origin is a package repository that contains all of the metadata (such as catalogs, manifests, and search indexes) and content (files) for one or more packages. If multiple origins are configured for a given publisher in an image, the package client API attempts to choose the best origin to retrieve package data from. This is the most common type of repository, and is implicitly created whenever pkgsend or pkgrecv is used on a package repository.

A mirror is a package repository that contains only package content (files). If one or more mirrors are configured for a given publisher in an image, the client API prefers the mirrors for package content retrieval and attempts to choose the best one to retrieve package content from. If the mirror is unreachable, does not have the required content, or is slower, the client API retrieves the content from any configured origin repositories. Mirrors are intended for content sharing among a trusted set of clients using the dynamic mirror functionality of pkg.depotd(8). Mirrors are also intended to be used to authenticate access to package metadata, but distribute the package content without authentication. For example, a client might be configured with an https origin that requires an SSL key and certificate pair to access, and with an http mirror that provides the package content. In this way, only authorized clients can install or update the packages, while the overhead of authentication for package content retrieval is avoided. A mirror can be created by removing all subdirectories of a repository except those named file and their parents. An origin repository can be also be provisioned as a mirror by using the mirror mode of pkg.depotd(8).

Global and Non-Global Zone Update

The pkg system forces non-global zones to be kept in sync with the global zone. This means that certain packages must be at the same version in the global zone and all non-global zones to ensure the same kernel is run. To do this, pkg uses parent dependencies to impose certain constraints on non-global zones. See “Depend Actions” above for more information about parent dependencies.

Because of restrictions that the global zone imposes on non-global zones, the non-global zones must have access to the packages of the global zone and must have a similar publisher configuration. Both of these objectives are achieved by using a system repository (see the pkg.sysrepo(8) man page). The system repository provides access to the publishers configured in the global zone and information about how those publishers are configured. To prevent non-global zones from choosing different packages during installation or update, system publishers are ranked higher in the publisher search order than publishers configured in the non-global zone. See the pkg set-publisher command in the pkg(1) man page for information about publisher search order.

To update all non-global zones on the system, use the pkg update command with no arguments in the global zone. This command operates on the global zone and on each non-global zone recursively. The minimal changes necessary are made to non-global zones to bring them in sync with the changes made in the global zone. For example, suppose package foo is installed at version 1 in both the global zone and non-global zones, and suppose version 2 is available in a system repository. If foo has a parent dependency, then pkg update foo updates foo to version 2 in both the global zone and the non-global zones because the parent dependency forces the package to stay in sync. If foo does not have a parent dependency, then foo is updated to version 2 in the global zone but remains at version 1 in the non-global zones.

Facets and Variants

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 and debug or non-debug binaries.

In IPS, optional components are called facets and mutually exclusive components are called variants. Facets and variants are specified as tags on package actions. Each facet and variant tag has a name and a value. A single action can have multiple facet and variant tags. Examples of components with multiple facet and variant tags include an architecture-specific header file that is used by developers, or a component that is only for a SPARC global zone.

An example of a variant tag is variant.arch=sparc. An example of a facet tag is facet.devel=true. Facets and variants are often referred to without the leading facet. and variant..

Facets and variants are special properties of the image and cannot be set on individual packages. To view the current values of the facets and variants set on the image, use the pkg facet and pkg variant commands as shown in the pkg(1) man page. To modify the values of the facets and variants set on the image, use the pkg change-facet and pkg change-variant commands.

Facets are treated as boolean values by package clients: Facets can be set only to true (enabled) or false (disabled) in the image. By default, all facets starting with 'facet.debug.' or 'facet.optional.' are considered to be set to false in the image; all others are considered to be set to true in the image.

Facets can be either set locally within an image using the pkg change-facet command or inherited from a parent image. For example, a non-global zone can inherit a facet from the global zone. Inherited facets are evaluated before, and take priority over, any locally set facets. If the same facet is both inherited and locally set, the inherited facet value masks the locally set value. Masked facets have no effect on facet evaluation and package actions. Facet changes made by using the pkg change-facet command only affect locally set facets. Inherited facets can only be changed by making the change in the parent image. By default, the pkg facet command does not display masked facets.

The value of a facet tag on an action can be set to all or true to control how clients filter faceted actions. All values other than all or true have undefined behavior. See below for a description of the conditions that must exist in the image to install an action that has facet tags.

The all value for a facet is useful when more than a single level of filtering is required. In the following example, foo.txt is installed only if the doc facet and at least one of the locale facets is true in the image. This enables administrators to exclude documentation, but still enable or disable support for specific locales. In addition, api.txt is only installed if both the doc and devel facets are true in the image.

file path=usr/share/doc/foo/foo.txt facet.doc=all facet.locale.en_GB=true facet.locale.en_US=true
file path=usr/share/doc/foo/api.txt facet.doc=all facet.devel=all

A facet set on the image can be a full facet such as doc.man or a pattern such as locale.*. This is useful when you want to disable a portion of the facet namespace, and only enable individual facets within it. 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
[output about packages being updated]
# pkg change-facet locale.en_US=true
[output about packages being updated]

Most variants can have any number of values. For example, the arch variant can be set to i386, sparc, ppc, arm, or whatever architectures the distribution supports. (Only i386 and sparc are used in Oracle Solaris.) The exception are the debug variants. The debug variants should only be set to true or false; other values have undefined behavior. If a file action has both non-debug and debug versions, both versions must have the applicable debug variant explicitly set, as shown in the following example:

file group=sys mode=0644 overlay=allow owner=root \
  path=etc/motd pkg.csize=115 pkg.size=103 preserve=true \
  variant.debug.osnet=true

file group=sys mode=0644 overlay=allow owner=root \
  path=etc/motd pkg.csize=68 pkg.size=48 preserve=true \
  variant.debug.osnet=false

The variant value must be set on the image in order for a package using the variant to be installed; by default all unspecified variants have the value 'false', which may or may not make the package installable. The arch and zone variants are set by the program that creates the image and installs its initial contents.

    The facets and variants set on the image affect whether a particular action is installed.

  • Actions with no facet or variant tags are always installed.

  • Actions with facet tags are installed if the following conditions exist in the image:

    • All facet tags on the action that have a value of all are true in the image (false is the default for all facets starting with 'facet.debug.' or 'facet.optional.'; true is the default for all others).

    • If any facet tags on the action have a value of true, at least one of those facets is true in the image.

  • Actions with variant tags are installed only if the values of all the variant tags are the same as the values set in the image.

  • Actions with both facet and variant tags are installed if both the facets and the variants allow the action to be installed.

You can create custom facet tags and variant tags. See Packaging and Delivering Software With the Image Packaging System in Oracle Solaris 11.4 for more information. The following tags are in common use in Oracle Solaris.

Variant Name
Possible Values
variant.arch
sparc, i386
variant.opensolaris.zone
global, nonglobal
variant.debug.*
true, false

The following list shows a small sample of the facet tags that are used in Oracle Solaris:

facet.devel             facet.doc
facet.doc.html          facet.doc.info
facet.doc.man           facet.doc.pdf
facet.locale.de         facet.locale.en_GB
facet.locale.en_US      facet.locale.fr
facet.locale.ja_JP      facet.locale.zh_CN

Image Policies

Image policies are defined by image properties with boolean values. See “Image Properties” in the pkg(1) man page for descriptions of the flush-content-cache-on-success and send-uuid properties and information about how to view and modify their values.

Files

Since pkg(7) images can be located arbitrarily within a larger file system, the token $IMAGE_ROOT is used to distinguish relative paths. For a typical system installation, $IMAGE_ROOT is equivalent to /.

$IMAGE_ROOT/var/pkg

Metadata directory for a full or partial image.

$IMAGE_ROOT/.org.opensolaris,pkg

Metadata directory for a user image.

Within the metadata of a particular image, certain files and directories can contain information useful during repair and recovery. The token $IMAGE_META is used to refer to the top-level directory that contains the metadata. $IMAGE_META is typically one of the two paths given above.

$IMAGE_META/lost+found

Location of conflicting directories and files moved during a package operation.

$IMAGE_META/publisher

Contains a directory for each publisher. Each directory stores publisher-specific metadata.

Other paths within the $IMAGE_META directory hierarchy are Private, and are subject to change.

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Availability
package/pkg
Interface Stability
Uncommitted

See Also

pkg(1), pkgsend(1), pkg.depotd(8), pkg.sysrepo(8), svcs(1), svcadm(8)

Updating Systems and Adding Software in Oracle Solaris 11.4

Creating Package Repositories in Oracle Solaris 11.4

Packaging and Delivering Software With the Image Packaging System in Oracle Solaris 11.4

https://github.com/oracle/solaris-ips