| Skip Navigation Links | |
| Exit Print View | |
|
Packaging and Delivering Software With the Image Packaging System in Oracle Solaris 11.1 Oracle Solaris 11.1 Information Library |
| Skip Navigation Links | |
| Exit Print View | |
|
|
Packaging and Delivering Software With the Image Packaging System in Oracle Solaris 11.1 Oracle Solaris 11.1 Information Library |
1. IPS Design Goals, Concepts, and Terminology
Tools for Software Self-Assembly
Examples of Software Self-Assembly in Oracle Solaris
Multiple Packages Delivering Configuration Fragments
2. Packaging Software With IPS
3. Installing, Removing, and Updating Software Packages
4. Specifying Package Dependencies
6. Modifying Package Manifests Programmatically
7. Automating System Change as Part of Package Installation
8. Advanced Topics For Package Updating
This section defines IPS terms and describes IPS components.
IPS is designed to install packages in an image. An image is a directory tree, and can be mounted in a variety of locations as needed. An image is one of the following three types:
In a full image, all dependencies are resolved within the image itself, and IPS maintains the dependencies in a consistent manner.
Non-global zone images are linked to a full image (the parent global zone image), but do not provide a complete system on their own. In a zone image, IPS maintains the non-global zone consistent with its global zone as defined by dependencies in the packages.
User images contain only relocatable packages.
In general, images are created or cloned by installers, beadm(1M), or zonecfg(1M), for example, rather than by pkg image-create.
Every IPS package is represented by a fault management resource identifier (FMRI) that consists of a publisher, a name, and a version, with the scheme pkg. In the following example package FMRI, solaris is the publisher, system/library is the package name, and 0.5.11,5.11-0.175.0.0.0.2.1:20111019T082311Z is the version:
pkg://solaris/system/library@0.5.11,5.11-0.175.1.0.0.2.1:20120919T082311Z
FMRIs can be specified in abbreviated form if the resulting FMRI is still unique. The scheme, publisher, and version can be omitted. Leading components can be omitted from the package name.
When the FMRI starts with pkg:// or //, the first word following // must be the publisher name, and no components can be omitted from the package name. When no components are omitted from the package name, the package name is considered complete, or rooted.
When the FMRI starts with pkg:/ or /, the first word following the slash is the package name, and no components can be omitted from the package name. No publisher name can be present.
When the version is omitted, the package generally resolves to the latest version of the package that can be installed.
A publisher is an entity that develops and constructs packages. A publisher name, or prefix, identifies this source in a unique manner. Publisher names can include upper and lower case letters, numbers, hyphens, and periods: the same characters as a valid host name. Internet domain names or registered trademarks are good choices for publisher names, since these provide natural namespace partitioning.
Package clients combine all specified sources of packages for a given publisher when computing packaging solutions.
Package names are hierarchical with an arbitrary number of components separated by forward slash (/) characters. Package name components must start with a letter or number, and can include underscores (_), hyphens (-), periods (.), and plus signs (+). Package name components are case sensitive.
Package names form a single namespace across publishers. Packages with the same name and version but different publishers are assumed to be interchangeable in terms of external dependencies and interfaces.
Leading components of package names can be omitted if the package name that is used is unique. For instance, /driver/network/ethernet/e1000g can be reduced to network/ethernet/e1000g, ethernet/e1000g, or even simply e1000g. When no components are omitted from the package name, the package name is considered complete, or rooted. If the packaging client complains about ambiguous package names, specify more components of the package name or specify the full, rooted name. Package names should be chosen to reduce possible ambiguities as much as possible.
If an FMRI contains a publisher name, then the full, rooted package name must be specified.
Scripts should refer to packages by their full, rooted names.
FMRIs can also be specified using an asterisk (*) to match any portion of a package name. Thus /driver/*/e1000g and /dri*00g both expand to /driver/network/ethernet/e1000g.
A package version consists of four sequences of integer numbers, separated by punctuation. The elements in the first three sequences are separated by dots, and the sequences are arbitrarily long. Leading zeros in version elements are forbidden, to allow for unambiguous sorting by package version. For example, 01.1 and 1.01 are invalid version elements.
In the following example package version, the first sequence is 0.5.11, the second sequence is 5.11, the third sequence is 0.175.1.0.0.2.1, and the fourth sequence is 20120919T082311Z.
0.5.11,5.11-0.175.1.0.0.2.1:20120919T082311Z
The first sequence is the component version. For components that are developed as part of Oracle Solaris, this sequence represents the point in the release when this package last changed. For a component with its own development life cycle, this sequence is the dotted release number, such as 2.4.10.
The second sequence is the build version. This sequence, if present, must follow a comma. Oracle Solaris uses this sequence to denote the release of the OS for which the package was compiled.
The third sequence is the branch version, providing vendor-specific information. This sequence, if present, must follow a hyphen. This sequence can contain a build number or provide some other information. This value can be incremented when the packaging metadata is changed, independently of the component. See Oracle Solaris Package Versioning for a description of how the branch version fields are used in Oracle Solaris.
The fourth sequence is a time stamp. This sequence, if present, must follow a colon. This sequence represents the date and time the package was published in the GMT time zone. This sequence is automatically updated when the package is published
The package versions are ordered using left-to-right precedence: The number immediately after the @ is the most significant part of the version space. The time stamp is the least significant part of the version space.
The pkg.human-version attribute can be used to hold a human-readable version string, however the versioning scheme described above must also be present. The human-readable version string is only used for display purposes, as documented in Set Actions.
By allowing arbitrary version lengths, IPS can accommodate a variety of different models for supporting software. For example, a package author can use the build or branch versions and assign one portion of the versioning scheme to security updates, another for paid versus unpaid support updates, another for minor bug fixes, or whatever information is needed.
A version can also be the token latest, which specifies the latest version known.
Appendix B, How IPS Is Used To Package the Oracle Solaris OS describes how Oracle Solaris implements versioning.
Actions define the software that comprises a package; they define the data needed to create this software component. Package contents are expressed in a package manifest file as a set of actions.
Package manifests are largely created using programs. Package developers provide minimal information, and the manifest is completed using package development tools as described in Chapter 2, Packaging Software With IPS.
Actions are expressed in the following form in package manifest files:
action_name attribute1=value1 attribute2=value2 ...
In the following example action, dir indicates this action specifies a directory. Attributes in the form name=value describe properties of that directory:
dir path=a/b/c group=sys mode=0755 owner=root
The following example shows an action that has data associated with it. In this file action, the second field, which has no name= prefix, is called the payload:
file 11dfc625cf4b266aaa9a77a73c23f5525220a0ef path=etc/release owner=root \
group=sys mode=0444 chash=099953b6a315dc44f33bca742619c636cdac3ed6 \
pkg.csize=139 pkg.size=189 variant.arch=i386
In this example, the payload is the SHA-1 hash of the file. This payload can alternatively appear as a regular attribute with the name hash, as shown in the following example. If both forms are present in the same action, they must have identical values.
file hash=11dfc625cf4b266aaa9a77a73c23f5525220a0ef path=etc/release owner=root \
group=sys mode=0444 chash=099953b6a315dc44f33bca742619c636cdac3ed6 \
pkg.csize=139 pkg.size=189 variant.arch=i386
Action metadata is freely extensible. Additional attributes can be added to actions as needed. Attribute names cannot include spaces, quotation marks, or equals signs (=). Attribute values can have all of those, although values with spaces must be enclosed in single or double quotation marks. Single quotation marks need not be escaped inside a string enclosed in double quotation marks, and double quotation marks need not be escaped inside a string enclosed in single quotation marks. A quotation mark can be prefixed with a backslash (\) to prevent terminating the quoted string. Backslashes can be escaped with backslashes. Custom attribute names should use a unique prefix to prevent accidental namespace overlap. See the discussion of publisher names in Package Publisher.
Multiple attributes with the same name can be present and are treated as unordered lists.
Most actions have a key attribute. The key attribute is the attribute that makes this action unique from all other actions in the image. For file system objects, the key attribute is the path for that object.
The following sections describe each IPS action type and the attributes that define these actions. The action types are detailed in the pkg(5) man page, and are repeated here for reference. Each section contains an example action as it would appear in a package manifest during package creation. Other attributes might be automatically added to the action during publication.
The file action is by far the most common action. A file action represents an ordinary file. The file action references a payload, and has the following four standard attributes:
The file system path where the file is installed. This is the key attribute of a file action. The value of the path attribute is relative to the root of the image. Do not include the leading /.
The access permissions of the file. The value of the mode attribute is simple permissions in numeric form, not ACLs.
The name of the user that owns the file.
The name of the group that owns the file.
The payload is normally specified as a positional attribute: The payload is the first word after the action name and has no attribute name. In a published manifest, the payload value is the SHA-1 hash of the file contents. If the payload is present in a manifest that has not yet been published, it represents the path where the payload can be found, as explained in the pkgsend(1) man page. The named hash attribute must be used instead of the positional attribute if the payload value includes an equal symbol (=), double quotation mark ("), or space character. Both positional and hash attributes can be used in the same action, but the hashes must be identical.
A file action can also include the following attributes:
Specifies that the contents of the file should not be overwritten on upgrade if the contents are determined to have changed since the file was installed or last upgraded. On initial installs, if an existing file is found, that existing file is salvaged (stored in /var/pkg/lost+found).
The preserve attribute can have one of the following values:
The existing file is renamed with the extension .old, and the new file is put in its place.
The existing file is left alone, and the new file is installed with the extension .new.
This file is not installed for initial package installs. On upgrades, any existing file is renamed with the extension .legacy, and then the new file is put in its place.
The existing file is left alone, and the new file is not installed.
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. 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:
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.
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.
This attribute is used to handle editable files moving from package to package, from place to place, or both. The value of this attribute is the name of the originating package, followed by a colon, followed by 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.
Once this attribute is set, do not change its value, even if the package or file are repeatedly renamed. Keeping the same value permits upgrade to occur from all previous versions.
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.
This attribute is used to tag editable files that should be reverted as a set. Multiple revert-tag values can be specified The file reverts to its manifest-defined state when the pkg revert command is invoked with any of those tags specified. See the pkg(1) man page for information about the revert subcommand.
Specific types of files can have additional attributes. For ELF files, the following attributes are recognized:
The architecture of the ELF file. This value is the output of uname -p on the architecture for which the file is built.
This value is 32 or 64.
This value is the hash of the ELF sections in the file 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.
An example file action is:
file path=usr/bin/pkg owner=root group=bin mode=0755
The dir action is like the file action in that it represents a file system object, except that it represents a directory instead of an ordinary file. The dir action has the same four standard attributes as the file action (path, owner, group, and mode), and path is the key attribute.
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 /var/pkg/lost+found.
Use the following attribute to move unpackaged contents into a new directory:
Names a directory of salvaged items. A directory with such an attribute inherits on creation the salvaged directory contents if they exist. For an example, see Moving Unpackaged Contents on Directory Removal or Rename.
During installation, pkg(1) checks that all instances of a given directory action on the system have the same owner, group, and mode attribute values. The dir action is not installed if conflicting values are found on the system or in other packages to be installed in the same operation.
An example of a dir action is:
dir path=usr/share/lib owner=root group=sys mode=0755
The link action represents a symbolic link. The link action has the following standard attributes:
The file system path where the symbolic link is installed. This is the key attribute for a link action.
The target of the symbolic link. The file system object to which the link resolves.
The link action also takes attributes that allow for multiple versions or implementations of a given piece of software to be installed on the system at the same time. Such links are mediated, and allow administrators to easily toggle which links point to which version or implementation as desired. These mediated links are discussed in Delivering Multiple Implementations of an Application.
An example of a link action is:
link path=usr/lib/libpython2.6.so target=libpython2.6.so.1.0
The hardlink action represents a hard link. It has the same attributes as the link action, and path is also its key attribute
An example of a hardlink action is:
hardlink path=opt/myapplication/hardlink target=foo
The set action represents a package-level attribute, or metadata, such as the package description.
The following attributes are recognized:
The name of the attribute.
The value given to the attribute.
The set action can deliver any metadata the package author chooses. The following attribute names have specific meaning to the packaging system:
The name and version of the containing package.
One or more tokens that a pkg(5) 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 (:). The scheme is used by the packagemanager(1) GUI. A set of info.classification values is provided in Appendix A, Classifying Packages.
A brief synopsis of the description. This value is shown at the end of each line of pkg list -s output, as well as in one line of the output of pkg info. This value should be no longer than 60 characters. This value should describe what the package is, and should not repeat the name or version of the package.
A detailed description of the contents and functionality of the package, typically a paragraph or so in length. This value should describe why someone might want to install this package.
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. Package obsoletion is covered in Obsoleting Packages.
When true, the package has been renamed. The package must include one or more depend actions as well, which 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. Package renaming is covered in Renaming, Merging and Splitting Packages.
The version scheme used by IPS is strict and does not allow for letters or words in the pkg.fmri version field. If a commonly used human-readable version is available for a given package, that version can be set here. The value is displayed by IPS tools. This value is not used as a basis for version comparison and cannot be used in place of the pkg.fmri version.
Some additional informational attributes, as well as some used by Oracle Solaris are described in Appendix B, How IPS Is Used To Package the Oracle Solaris OS.
An example of a set action is:
set name=pkg.summary value="Image Packaging System"
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(1M) for more information about these attribute values.
The name of the driver. This is usually, but not always, the file name of the driver binary. This is the key attribute of the driver action.
An alias for the driver. A given driver can have more than one alias attribute. No special quoting rules are necessary.
A driver class. A given driver can have more than one class attribute.
The file system permissions for the device nodes of the driver.
The file system permissions for the minor nodes of the clone driver for this driver.
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.
Privileges used by the driver. A given driver can have more than one privs attribute.
An entry in /etc/devlink.tab. The value is the exact line to go into the file, with tabs denoted by \t. See the devlinks(1M) man page for more information. A given driver can have more than one devlink attribute.
An example of a driver action is:
driver name=vgatext \
alias=pciclass,000100 \
alias=pciclass,030000 \
alias=pciclass,030001 \
alias=pnpPNP,900 variant.arch=i386 variant.opensolaris.zone=global
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 are covered in Chapter 4, Specifying Package Dependencies.
The following attributes are recognized:
The FMRI representing the target of the dependency. This is the key attribute of the depend action. The FMRI value must not include the publisher. The package name is assumed to be complete (that is, rooted), even if it does not begin with a forward slash (/). Dependencies of type 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.
The FMRI value cannot use asterisks (*), and cannot use the latest token for a version.
The type of the dependency.
The target package 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 require dependencies cannot be satisfied.
The dependency target, if present, must be at the specified version level or greater.
The containing package cannot be installed if the dependency target is present at the specified version level or greater. If no version is specified, the target package cannot be installed concurrently with the package specifying the dependency.
The dependency is optional, but the version of the target package is constrained. See Chapter 4, Specifying Package Dependencies for a discussion of constraints and freezing.
Any one of multiple target packages as specified by multiple fmri attributes can satisfy the dependency, following the same rules as the require dependency type.
The dependency target is required only if the package defined by the predicate attribute is present on the system.
Prior to installation of this package, the dependency target must, if present, be at the specified value or greater on the image to be modified. If the value of the root-image attribute is true, the target must be present on the image rooted at / in order to install this package.
The dependency target 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 the pkg(1) man page for information about the image avoid list.
The dependency is ignored if the image is not a child image, such as a zone. If the image is a child image, then the dependency target must be present in the parent image. The version matching for a parent dependency is the same as that used for incorporate dependencies.
The FMRI that represents the predicate for conditional dependencies.
Has an effect only for origin dependencies as mentioned above.
An example of a depend action is:
depend fmri=crypto/ca-certificates type=require
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 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. The license action payload 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 or accepted. The method of display or acceptance is at the discretion of clients.
The following attributes are recognized:
Provides a meaningful description for the license to assist users in determining the contents without reading the license text itself. This is the key attribute of the license action.
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
Wherever possible, including the version of the license in the description is recommended as shown above. The license value must be unique within a package.
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.
When true, the payload of the license action must be displayed by clients during packaging operations. Omission of this attribute is equivalent to false. This attribute should not be used for copyright notices, but only for actual licenses or other material that must be displayed during operations. The method of display is at the discretion of clients.
An example of a license action is:
license license="Apache v2.0"
The legacy action represents package data used by the legacy SVR4 packaging system. The attributes associated with the legacy action are added into the databases of the legacy SVR4 packaging system so that the tools querying those databases can operate as if the legacy package were actually installed. In particular, specifying the legacy action should cause the package named by the pkg attribute to satisfy SVR4 dependencies.
The following attributes are recognized. See the pkginfo(4) man page for description of the associated parameters.
The value for the CATEGORY parameter. The default value is system.
The value for the DESC parameter.
The value for the HOTLINE parameter.
The value for the NAME parameter. The default value is none provided.
The abbreviation for the package being installed. The default value is the name from the FMRI of the package. This is the key attribute of the legacy action.
The value for the VENDOR parameter.
The value for the VERSION parameter. The default value is the version from the FMRI of the package.
An example of a legacy action is:
legacy pkg=SUNWcsu arch=i386 category=system \
desc="core software for a specific instruction-set architecture" \
hotline="Please contact your local service provider" \
name="Core Solaris, (Usr)" vendor="Oracle Corporation" \
version=11.11,REV=2009.11.11 variant.arch=i386
Signature actions are used as part of the support for package signing in IPS. Signature actions are covered in detail in Chapter 9, Signing IPS Packages.
The user action defines a UNIX user as specified in the /etc/passwd, /etc/shadow, /etc/group, and /etc/ftpd/ftpusers files. Information from user actions is added to the appropriate files.
The following attributes are recognized:
The unique name of the user.
The encrypted password of the user. The default value is *LK*.
The unique numeric ID of the user. The default value is the first free value under 100.
The name of the user's primary group. This name must be found in /etc/group.
The real name of the user, as represented in the GECOS field in /etc/passwd. The default value is the value of the username attribute.
The user's home directory. The default value is /.
The user's default shell. The default value is empty.
Secondary groups to which the user belongs. See the group(4) man page.
Can be set to true or false. The default value of true indicates that the user is permitted to login via FTP. See the ftpusers(4) man page.
The number of days between January 1, 1970, and the date that the password was last modified. The default value is empty.
The minimum number of days required between password changes. This field must be set to 0 or above to enable password aging. The default value is empty.
The maximum number of days the password is valid. The default value is empty. See the shadow(4) man page.
The number of days before password expires that the user is warned.
The number of days of inactivity allowed for the user. This is counted on a per-machine basis. The information about the last login is taken from the machine's lastlog file.
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.
Set to empty.
A example of a user action is:
user gcos-field="pkg(5) server UID" group=pkg5srv uid=97 username=pkg5srv
The group action defines a UNIX group as specified in the group(4) file. No support is provided for group passwords. Groups defined with the group action initially have no user list. Users can be added with the user action.
The following attributes are recognized:
The value for the name of the group.
The unique numeric ID of the group. The default value is the first free group under 100.
An example of a group action is:
group groupname=pkg5srv gid=97
A software repository contains packages for one or more publishers. Repositories can be configured for access in a variety of different ways: HTTP, HTTPS, file (on local storage or via NFS or SMB), and as a self-contained package archive file, usually with the .p5p extension.
Package archives allow for convenient distribution of IPS packages, and are discussed further in Publish as a Package Archive.
A repository accessed via HTTP or HTTPS has a server process, pkg.depotd, associated with it. See the pkg.depotd(1M) man page for more information. For an example, see Retrieving Packages Using an HTTP Interface in Copying and Creating Oracle Solaris 11.1 Package Repositories.
In the case of file repositories, the repository software runs as part of the accessing client. Repositories are created with the pkgrepo and pkgrecv commands as shown in Copying and Creating Oracle Solaris 11.1 Package Repositories.
|