2573N/A.. The contents of this file are subject to the terms of the
2573N/A Common Development and Distribution License (the "License").
2573N/A You may not use this file except in compliance with the License.
2573N/A See the License for the specific language governing permissions
2573N/A and limitations under the License.
2573N/A.. When distributing Covered Code, include this CDDL HEADER in each
2573N/A If applicable, add the following below this CDDL HEADER, with the
2573N/A fields enclosed by brackets "[]" replaced with your own identifying
2573N/A information: Portions Copyright [yyyy] [name of copyright owner]
2573N/A.. Copyright (c) 2011, Oracle
and/or its affiliates. All rights reserved.
2525N/AThis chapter lays out the basic terminology used in the Image Packaging
2525N/ASystem and describes the various components.
2525N/AIPS is designed to install packages in an image. An image is a directory
2525N/Atree, and can be mounted in a variety of locations as needed. Images
2573N/A in a full image, all dependencies are resolved within the
2525N/A image itself and IPS maintains the dependencies in a consistent
2573N/A in a zone image, IPS maintains the zone consistent with its
2525N/A global zone as defined by dependencies in the packages.
2573N/A not yet fully functional for Solaris;
2525N/AIn general, images are created or cloned by other software (installers,
2525N/Abeadm, zonecfg, etc) rather than by the user.
2525N/AIPS deals with all software installed on a system in the granularity of
2525N/Apackages. A package consists of actions. Every package has a publisher,
2525N/Aa name and a version; these are represented by a fault management
2573N/Aresource identifier (FMRI) with the scheme 'pkg:'. For example::
2525N/A'0.5.11,5.11-0.168:20110618T001946Z' is the version.
2525N/AThe publisher information is optional; if present, it must be preceded by
2525N/A'pkg://'. An FMRI that includes the publisher is referred to as
2525N/Abeing "fully qualified". FMRIs without publisher information may omit
2525N/Athe scheme. If included, it should be of the form 'pkg:/' to indicate
2525N/Athat the first component is part of the package name rather than the
2525N/APackage names are hierarchal with components separated by '/'
2525N/Acharacters and can be arbitrarily deep. Package names form a single
2525N/Aname space across publishers; packages with the same name and version
2525N/Abut different publishers are assumed to be interchangable in terms of
2573N/Aexternal dependencies and interfaces. Package cname components are case
2525N/Asensitive and must start with a letter or number, but may include
2525N/A[_-.+] characters in latter positions.
2525N/AA package version consists of four sequences of integer numbers,
2525N/Aseparated by punctuation. The elements in the first three sequences
2525N/Aare separated by dots, and the sequences are arbitrarily long.
2525N/ALeading zeros in version components (
e.g. 01.1 or 1.01) are not
2525N/AThe first part is the component version. For components that are
2525N/Aare developed as part of Solaris, this will represent the point
2525N/Ain the release when this package last changed. For a component with its
2525N/Aown development lifecycle, this sequence will be the dotted release
2525N/Anumber, such as '2.4.10'. For a detailed discussion of how Solaris
2573N/Aversions its packages, see *Chapter 12*, Solaris and IPS.
2525N/AThe second part, which if present must follow a comma, is the build
2525N/Aversion. Solaris uses this to define for which minor release of Solaris
2525N/AThe third part, which if present must follow a dash, is the branch
2525N/Aversion, a versioning component, providing vendor-specific
2525N/Ainformation. This may be incremented when the packaging metadata is
2525N/Achanged, independently of the component, may contain a build number,
2525N/Aor some other information. Solaris usage of this field is detailed
2525N/AThe fourth part, which if present must follow a colon, is a timestamp.
2525N/AIt represents when the package was published in GMT time.
2525N/AThe package versions are ordered using left-to-right precedence; thus
2525N/Athe timestamp is the least significant part of the version space; the
2525N/Anumber immediately after the '@' is the most significant.
2525N/AA name that identifies the source of the packages in a unique manner.
2525N/AUsing Internet domains or trademarks the developer's organization owns
2525N/Aworks well here. Package clients combine all specified sources of
2525N/Apackages for a given publisher together when computing packaging
2525N/Asolutions. Publisher names may include upper and lower case
2525N/Aletters, numbers, dashes and periods - the same characters as a
2525N/AActions are used to define the software that comprises a package; they
2525N/Adefine the data needed to create this software component. A set of
2525N/Aactions are collected in a package manifest, where they appear as
2573N/Alines of text. Actions look like this::
2573N/A <action name> <attribute1>=<value1> <attribute2>=<value2> ...
2573N/A dir group=sys mode=0755 owner=root path=a/b/c
2525N/AThe first field identifies this as a dir (or directory) action; the
2573N/A*name*=*value* attributes describe the familiar properties of that
2525N/Adirectory. In the cases where the action has data associated with it,
2573N/Asuch as a file, the action looks like this::
2573N/A file 3b16e0d6cee005c580fb4967f291ff4708d23d97 \
2573N/A chash=de19003ae941249d372b93dedb526dd17004be81 group=sys \
2525N/AHere the second attribute (without a name= prepending it) is the sha1
2525N/Ahash of the file. This attribute may alternately appear as a regular
2573N/Aattribute with the name ``hash``; if both forms are present they must
2525N/Amatch. The sha1 hash of the compressed file appears as a normal
2525N/AAction metadata is freely extensible; additional attributes can be
2525N/Aadded to actions as desired. Attribute names may not include spaces,
2525N/Aquotes or '=' characters. Attribute values may have all of those,
2525N/Aalthough spaces must be enclosed in single or double quotes. Single
2525N/Aquotes need not be escaped inside of a double-quoted string, and vice
2525N/Aversa, though a quote may be prefixed with a backslash ("\") so as not
2525N/Ato terminate the quoted string. Backslashes may be escaped with
2525N/AMultiple attributes with the same name may be present and are
2525N/ANote that manifests are largely created using programs; it is not
2525N/Aexpected that that developers produce complete manifests by hand.
2525N/AMost actions have key attributes; this attribute is that makes this
2525N/Aaction unique from all others in the image. For file system
2525N/Aobjects, this is the path for that object.
2525N/AThere are currently twelve action types in IPS. The following
2525N/Asection describes each action type, and the attributes that
2573N/A The ``file`` action is by far the most common action, and represents an
2525N/A 'ordinary file'. It references a payload, and has four standard
2573N/A The filesystem path where the file is installed. This is a
2525N/A file action's key attribute.
2573N/A The access permissions (in numeric form) of the file. These
2525N/A are simple Unix-style permissions only, not ACLs.
2573N/A The name of the user which owns the file.
2573N/A The name of the group which owns the file.
2525N/A The payload is a "positional" attribute, in that it is not named. It
2525N/A is the first word after the action name. In a published manifest, it
2525N/A is the SHA-1 hash of the file contents. If present in a manifest that
2525N/A has yet to be published, it represents the path at which the payload
2525N/A may be found (see pkgsend(1)). The "hash" attribute may be used
2525N/A instead of the positional attribute, should the value include an
2525N/A equals sign. Both may be used in the same action; however, the hashes
2573N/A This specifies that the file's contents should not be
2525N/A overwritten on upgrade if they are determined to have
2525N/A changed since it was installed or last upgraded. On
2525N/A initial installs, if an existing file is found, it will
2573N/A * If the value of preserve is ``renameold``, then the existing
2573N/A file will be renamed with the extension '.old', and the new
2573N/A file will be put in its place.
2573N/A * If the value of preserve is ``renamenew``, then the existing
2573N/A file will be left alone, and the new file will be installed
2573N/A * If the value of preserve is ``legacy``, then this file will not
2573N/A be installed for initial package installs. On upgrades, any
2573N/A existing file will be renamed with the extension '.legacy',
2573N/A and then the new file will be put in its place.
2573N/A * If the value of preserve is ``true`` (or a value not listed
2573N/A above, such as ``strawberry``), then the existing file will
2573N/A be left alone, and the new file will not be installed.
2573N/A This specifies whether the action allows other packages to
2525N/A deliver a file at the same location or whether it delivers
2525N/A a file intended to overlay another. This functionality is
2525N/A intended for use with configuration files that don't
2525N/A If overlay is not specified, multiple packages may not deliver
2525N/A files to the same location.
2573N/A * If the value of overlay is ``allow``, one other package is
2573N/A allowed to deliver a file to the same location. This value
2573N/A has no effect unless the preserve attribute is also set.
2573N/A * If the value of overlay is ``true``, the file delivered by the
2573N/A action will overwrite any other action that has specified
2573N/A ``allow``. Changes to the installed file will be preserved
2573N/A based on the value of the preserve attribute of the overlaying
2573N/A file. On removal, the contents of the file will be preserved
2573N/A if the action being overlayed is still installed regardless of
2573N/A whether the preserve attribute was specified. Only one action
2573N/A may overlay another, and the ``mode``, ``owner``, and ``group``
2525N/A Files may also be 'tasted', and depending on the flavor, may have
2525N/A additional interesting attributes. For ELF files, the following
2573N/A The architecture of the ELF file. This will be the output of
2573N/A ``uname -p`` on the architecture for which the file is built.
2573N/A This is the hash of the 'interesting' ELF sections in
2525N/A the file. These are the sections that are mapped into
2525N/A memory when the binary is loaded, and are the only ones
2525N/A necessary to consider when determining whether two
2525N/A binaries' executable behavior will differ.
2573N/A This attribute is used to handle editable files moving
2525N/A from package to package or from place to place, or
2525N/A both. The form this takes is the name of the
2525N/A originating package, followed by a colon and the
2525N/A original path to the file. Any file being deleted
2525N/A is recorded either with its package and path, or
2525N/A with the value of the original_name attribute if
2525N/A specified. Any editable file being installed that
2573N/A has the ``original_name`` attribute set will use the
2525N/A file of that name if it is deleted as part of the
2525N/A same packaging operation. Note that once set, this
2525N/A attribute should never change even the package or
2525N/A file are repeatedly renamed; this will permit
2525N/A upgrade to occur from all previous versions.
2573N/A This attribute is used to tag editable files that should
2573N/A be reverted as a set. Multiple ``revert-tag`` values may
2573N/A be specified; the file will revert to its manifest-defined
2573N/A state when ``pkg revert`` is invoked with any of those tags
2573N/A The ``dir`` action is like the file action in that it represents a
2525N/A filesystem object, but a directory instead of an ordinary file. It
2573N/A has the same four standard attributes as the file action, and ``path``
2525N/A Directories are reference counted in IPS. When the last package
2525N/A that either explicitly or implicitly references a directory no
2525N/A longer does so, that directory is removed. If there are
2525N/A unpackaged file system objects under that directory, those items
2525N/A If it is desirable to move unpackaged contents into a new directory,
2525N/A this attribute will be useful:
2525N/A This names a directory of salvaged items. A directory with
2525N/A such an attribute will inherit on creation the salvaged directory
2573N/A During installation, pkg(1) will check that all instances of a given
2573N/A directory action on the system have the same owner, group and mode
2573N/A attributes, and will not install the action if conflicting actions
2573N/A The ``link`` action represents a symbolic link. It has two standard
2525N/A The filesystem path where the symlink is installed. This is a
2525N/A link action's key attribute.
2525N/A The target of the symlink; the filesystem object to which the
2573N/A The ``link`` action also takes attributes that allow for multiple
2573N/A implementations of a given piece of software to be installed on the
2573N/A system at the same time. Link actions are installed that that are
2573N/A *mediated*, allowing administrators to easily toggle which links
2573N/A point to which implementation as desired. These *mediated links* are
2573N/A The ``hardlink`` action represents a hard link. It has the same
2573N/A attributes as the link action, and ``path`` is also its key attribute.
2573N/A The ``driver`` action represents a device driver. It does not reference
2525N/A a payload: the driver files themselves must be installed as file
2525N/A actions. The following attributes are recognized (see add_drv(1M) for
2573N/A The name of the driver. This is usually, but not always,
2525N/A the filename of the driver binary. This is the driver
2573N/A This represents an alias for the driver. There may be
2525N/A more than one alias attribute for any given driver.
2525N/A There are no special quoting rules necessary.
2573N/A This represents a driver class. There may be more than
2525N/A one class attribute for any given driver.
2573N/A This represents the filesystem permissions for the
2573N/A This represents the filesystem permissions for the
2525N/A "clone" driver's minor nodes for this driver.
2573N/A This specifies additional security policy for the device.
2525N/A There may be more than one policy attribute for any given
2525N/A driver, but no minor device specification may be present in
2573N/A This specifies privileges used by the driver. There may
2525N/A be more than one privs attribute for any given driver.
2525N/A is the exact line to go into the file, with tabs denoted
2525N/A by "\t". See devlinks(1M) for more information. There
2525N/A may be more than one devlink attribute for any given
2573N/A The ``depend`` action represents an inter-package dependency. A package
2525N/A may depend on another package because the first requires functionality
2525N/A in the second for the functionality in the first to work, or even to
2573N/A install. Dependencies are covered in more detail in *Chapter 6*.
2525N/A The following attributes are recognized:
2573N/A The type of the dependency.
2573N/A * If the value is ``require``, then the
2573N/A dependency is required. A package cannot be installed if any of
2573N/A its required dependencies cannot be satisfied.
2573N/A * If the value is ``optional``, then the dependency, if present, must
2573N/A be at the specified version level or greater.
2573N/A * If the value is ``exclude``, then the containing package cannot
2573N/A be installed if the dependency is present at the specified
2573N/A * If the value is ``incorporate``, then the dependency is
2573N/A optional, but the version of the dependent package will
2573N/A become constrained. See *Chapter 6* for a discussion of
2573N/A constraints and freezing. XXX need to write that.
2573N/A * If the value is ``require-any``, then any one of multiple dependent
2573N/A packages as specified by multiple ``fmri`` attributes will satisfy
2573N/A * If the value is ``conditional``, the dependency is required
2573N/A only if the package defined by the predicate attribute is present
2573N/A * If the value is ``origin``, the dependency must, if present,
2573N/A be at the specified value or better on the image to be modified
2573N/A prior to installation. If the value of the ``root-image`` attribute
2573N/A is ``true``, the dependency must be present on the image rooted at '/'
2573N/A in order to install this package.
2573N/A * If the value is ``group``, the dependency is required unless the
2573N/A package is on the image avoid list. Note that obsolete packages
2573N/A silently satisfy the group dependency. See the avoid subcommand
2573N/A * If the value is ``parent``, then the dependency is ignored if
2573N/A the image is not a child image. If the image is a child
2573N/A image then it's required that the dependency be present in
2573N/A the parent image. The package version matching for a
2573N/A ``parent`` dependency is the same as that used for ``incorporate``
2573N/A The FMRI representing the depended-upon package. It must not
2573N/A include the publisher. In the case of ``require-any`` dependencies,
2525N/A there may be multiple values. This is the dependency action's
2573N/A The FMRI representing the predicate for ``conditional``
2573N/A Has an effect only for ``origin`` dependencies as mentioned above.
2573N/A The ``license`` action represents a license or other informational
2525N/A file associated with the package contents. A package may deliver
2525N/A licenses, disclaimers, or other guidance to the package installer
2525N/A through the use of the license action.
2525N/A The payload of the license action will be delivered into the image
2525N/A metadata directory related to the package, and should only contain
2525N/A human-readable textual data. It should not contain HTML or any
2525N/A other form of markup. License actions, through attributes, may
2525N/A indicate to clients that the related payload must be displayed
2525N/A and/or require "acceptance" of it. Please note that the exact
2525N/A method of display
and/or acceptance is at the discretion of
2525N/A The following attributes are recognized:
2573N/A This attribute provides a meaningful description
2525N/A for the license to assist users in determining
2525N/A the contents without reading the license text
2525N/A itself. Some example values might include:
2573N/A * "ABC Co. Copyright Notice"
2573N/A * "Common Development and Distribution License 1.0 (CDDL)"
2573N/A * "GNU General Public License 2.0 (GPL)"
2573N/A * "GNU General Public License 2.0 (GPL) Only"
2573N/A * "Mozilla Public License 1.1 (MPL)"
2525N/A Wherever possible, including the version of the
2525N/A license in the description is recommended as shown
2525N/A above. This value must be unique within a package.
2573N/A When ``true``, this license must be accepted by a
2525N/A user before the related package can be installed
2525N/A or updated. Omission of this attribute will be
2573N/A considered equivalent to ``false``. The method of
2525N/A acceptance (interactive, configuration-based,
2525N/A etc.) is at the discretion of clients.
2573N/A When ``true``, the action's payload must be displayed
2525N/A by clients during packaging operations. Omission of
2573N/A this value is considered equivalent to ``false``.
2525N/A This attribute should not be used for copyright
2525N/A notices, only actual licenses or other material
2525N/A that must be displayed during operations. The
2525N/A method of display is at the discretion of
2573N/A The ``license`` attribute is the key attribute for the license action.
2573N/A The ``legacy`` action represents package data used by a legacy
2525N/A packaging system. The attributes associated with this action are
2525N/A added into the legacy system's databases in order that the tools
2525N/A querying those databases might operate as if the legacy package were
2525N/A actually installed. In particular, this should be sufficient to
2525N/A convince the legacy system that the package named by the 'pkg'
2525N/A attribute is installed on the system, so that it may be used to
2525N/A The following attributes, named in accordance with the parameters on
2525N/A pkginfo(4), are recognized:
2573N/A The value for the CATEGORY parameter. The default value
2573N/A The value for the DESC parameter.
2573N/A The value for the HOTLINE parameter.
2573N/A The value for the NAME parameter. The default value is
2573N/A The abbreviation for the package being installed. The
2525N/A default value is the name from the package's FMRI.
2573N/A The value for the VENDOR parameter.
2573N/A The value for the VERSION parameter. The default value is
2525N/A the version from the package's FMRI.
2573N/A The ``pkg`` attribute is the key attribute for the legacy action.
2573N/A The ``set`` action represents a package-level attribute, or metadata,
2525N/A such as the package description.
2525N/A The following attributes are recognized:
2573N/A The value given to the attribute.
2525N/A The set action can deliver any metadata the package author chooses;
2525N/A however, there are a number of well-defined attribute names which have
2525N/A specific meaning to the packaging system.
2573N/A The name and version of the containing package.
2573N/A One or more tokens which a pkg(5) client may use
2525N/A to classify the package. The value should have
2525N/A separated by a colon (:). The first is used
2573N/A A detailed description of the contents and
2525N/A functionality of the package, typically a
2573N/A A brief synopsis of the description.
2573N/A When ``true``, the package is marked obsolete. An
2525N/A obsolete package may have no actions other than
2525N/A more set actions, and must not be marked renamed.
2573N/A When ``true``, the package has been renamed.
2573N/A There must be one or more ``depend`` actions in
2525N/A the package as well which point to the package
2573N/A The version scheme used by IPS is strict, and
2573N/A version field. If there's a commonly used
2573N/A human-readable version available for a given package,
2573N/A that can be set here, and will be displayed by
2573N/A IPS tools. It does not get used as a basis for
2573N/A version comparison and cannot be used in place of
2573N/A Signature actions are used as part of the support for package signing in
2573N/A IPS. They are covered in detail in *Chapter 11*
2525N/AA software repository contains packages for one or more publishers.
2525N/ARepositories can be configured for access in a variety of different
2525N/Aways: http, https, file (local or via NFS or SMB) and as a
2573N/Aself-contained archive file, usually with the '.p5p' extension.
2525N/AA repository accessed via http or https has a server process associated
2525N/Awith it; in the case of file repos the repository software runs as
2525N/Apart of the accessing client.
2525N/ARepositories are created with the pkgrepo(1) command.