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
2525N/A Full - in a full image, all dependencies are resolved within the
2525N/A image itself and IPS maintains the dependencies in a consistent
2525N/A Zone - in a zone image, IPS maintains the zone consistent with its
2525N/A global zone as defined by dependencies in the packages.
2525N/A User - 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
2525N/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
2525N/Aexternal dependencies and interfaces. Package cname componets 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
2525N/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
2525N/Alines of text. Actions look like this:
2525N/A<action name> <attribute1>=<value1> <attribute2>=<value2> ...
2525N/Adir group=sys mode=0755 owner=root path=a/b/c
2525N/AThe first field identifies this as a dir (or directory) action; the
2525N/A'name'='value' attributes describe the familiar properties of that
2525N/Adirectory. In the cases where the action has data associated with it,
2525N/Asuch as a file, the action looks like this:
2525N/Afile 3b16e0d6cee005c580fb4967f291ff4708d23d97 \
2525N/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
2525N/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
2525N/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
2525N/A path The filesystem path where the file is installed. This is a
2525N/A file action's key attribute.
2525N/A mode The access permissions (in numeric form) of the file. These
2525N/A are simple Unix-style permissions only, not ACLs.
2525N/A owner The name of the user which owns the file.
2525N/A group 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
2525N/A preserve 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
2525N/A If the value of preserve is 'renameold', then the existing
2525N/A file will be renamed with the extension '.old', and the new
2525N/A file will be put in its place.
2525N/A If the value of preserve is 'renamenew', then the existing
2525N/A file will be left alone, and the new file will be installed
2525N/A If the value of preserve is 'legacy', then this file will not
2525N/A be installed for initial package installs. On upgrades, any
2525N/A existing file will be renamed with the extension '.legacy',
2525N/A and then the new file will be put in its place.
2525N/A If the value of preserve is 'true' (or a value not listed
2525N/A above, such as 'strawberry'), then the existing file will
2525N/A be left alone, and the new file will not be installed.
2525N/A overlay 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.
2525N/A If the value of overlay is 'allow', one other package is
2525N/A allowed to deliver a file to the same location. This value
2525N/A has no effect unless the preserve attribute is also set.
2525N/A If the value of overlay is 'true', the file delivered by the
2525N/A action will overwrite any other action that has specified
2525N/A 'allow'. Changes to the installed file will be preserved
2525N/A based on the value of the preserve attribute of the overlaying
2525N/A file. On removal, the contents of the file will be preserved
2525N/A if the action being overlayed is still installed regardless of
2525N/A whether the preserve attribute was specified. Only one action
2525N/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
2525N/A elfarch The architecture of the ELF file. This will be the output of
2525N/A 'uname -p' on the architecture for which the file is built.
2525N/A elfbits This will be '32' or '64'.
2525N/A elfhash 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.
2525N/A original_name 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
2525N/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.
2525N/A revert-tag This attribute is used to tag editable files that should
2525N/A be reverted as a set. Multiple revert-tag values may
2525N/A be specified; the file will revert to its manifest-defined
2525N/A state when pkg revert is invoked with any of those tags
2525N/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
2525N/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 information about $IMAGE_META.
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
2525N/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
2525N/A Specifies the entry in the mediation namespace shared by all
2525N/A pathnames participating in a given mediation group (
e.g. 'python').
2525N/A Link mediation may be performed based on 'mediator-version'
and/or 2525N/A 'mediator-implementation'. All mediated links for a given pathname
2525N/A must specify the same mediator. However, not all mediator versions
2525N/A and implementations need to provide a link at a given path. If a
2525N/A mediation doesn't provide a link, then the link is removed when that
2525N/A mediation is selected. A mediator, in combination with a specific
2525N/A version
and/or implementation represents a 'mediation' that can be
2525N/A selected for use by the packaging system.
2525N/A Specifies the version (expressed as a dot-separated sequence
2525N/A of non-negative integers) of the interface described by the
2525N/A 'mediator' attribute. This attribute is required if 'mediator'
2525N/A is specified and 'mediator-implementation' is not. A local
2525N/A system administrator may set the version to use explicitly. The
2525N/A value specified should generally match the version of the package
2525N/A version=2.6), although this is not required.
2525N/A Specifies the implementation of the mediator for use in addition to
2525N/A or instead of the 'mediator-version'. Implementation strings are
2525N/A not considered to be ordered and one will be arbitrary selected by
2525N/A pkg(5) if not explicitly specified by a system administrator.
2525N/A The value can be a string of arbitrary length composed of alpha-
2525N/A numeric characters and spaces. If the implementation itself can
2525N/A be or is versioned, then the version should be specified at the
2525N/A end of the string, after a '@' (expressed as a dot-separated
2525N/A sequence of non-negative integers). If multiple versions of an
2525N/A implementation exist, the default behvaiour is to select the
2525N/A implementation with the greatest version.
2525N/A If only one instance of an implementation-mediation link at a
2525N/A particular path is installed on a system, then that one will be
2525N/A chosen automatically. If future links at the path are installed,
2525N/A the link will not be switched unless a vendor, site, or local
2525N/A override applies, or if one of the links is version-mediated.
2525N/A When resolving conflicts in mediated links, pkg(5) will normally
2525N/A choose the link with the greatest value of 'mediator-version' or
2525N/A based on 'mediator-implementation' if that is not possible. This
2525N/A attribute is used to specify an override for the normal conflict
2525N/A If this attribute is not specified, the default mediator selection
2525N/A If the value is 'vendor', the link will be preferred over those
2525N/A that do not have a 'mediator-priority' specified.
2525N/A If the value is 'site', the link will be preferred over those that
2525N/A have a value of 'vendor' or that do not have a 'mediator-priority'
2525N/A A local system administrator may override the selection logic
2525N/A The 'hardlink' action represents a hard link. It has the same
2525N/A attributes as the link action, and 'path' is also its key attribute.
2525N/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
2525N/A name The name of the driver. This is usually, but not always,
2525N/A the filename of the driver binary. This is the driver
2525N/A alias 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.
2525N/A class This represents a driver class. There may be more than
2525N/A one class attribute for any given driver.
2525N/A perms This represents the filesystem permissions for the
2525N/A clone_perms This represents the filesystem permissions for the
2525N/A "clone" driver's minor nodes for this driver.
2525N/A policy 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
2525N/A privs 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
2525N/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
2525N/A install. Dependencies may be optional.
2525N/A The following attributes are recognized:
2525N/A type The type of the dependency. If the value is 'require', then the
2525N/A dependency is required. A package cannot be installed if any of
2525N/A its required dependencies cannot be satisfied.
2525N/A If the value is 'optional', then the dependency, if present, must
2525N/A be at the specified version level or greater.
2525N/A If the value is 'exclude', then the containing package cannot
2525N/A be installed if the dependency is present at the specified
2525N/A If the value is 'incorporate', then the dependency is
2525N/A optional, but the version of the dependent package will
2525N/A become constrained. See 'Constraints and Freezing' below.
2525N/A If the value is 'require-any', then any one of multiple dependent
2525N/A packages as specified by multiple 'fmri' attributes will satisfy
2525N/A If the value is 'conditional', the dependency is required
2525N/A only if the package defined by the predicate attribute is present
2525N/A If the value is 'origin', the dependency must, if present,
2525N/A be at the specified value or better on the image to be modified
2525N/A prior to installation. If the value of the 'root-image' attribute
2525N/A is 'true', the dependency must be present on the image rooted at '/'
2525N/A in order to install this package.
2525N/A If the value is 'group', the dependency is required unless the
2525N/A package is on the image avoid list. Note that obsolete packages
2525N/A silently satisfy the group dependency. See the avoid subcommand
2525N/A If the value is 'parent', then the dependency is ignored if
2525N/A the image is not a child image. If the image is a child
2525N/A image then it's required that the dependency be present in
2525N/A the parent image. The package version matching for a
2525N/A 'parent' dependency is the same as that used for 'incorporate'
2525N/A fmri The FMRI representing the depended-upon package. It must not
2525N/A include the publisher. In the case of require-any dependencies,
2525N/A there may be multiple values. This is the dependency action's
2525N/A predicate The FMRI representing the predicate for 'conditional'
2525N/A root-image Has an effect only for origin dependencies as mentioned
2525N/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:
2525N/A license 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:
2525N/A "Common Development and Distribution License 1.0 (CDDL)"
2525N/A "GNU General Public License 2.0 (GPL)"
2525N/A "GNU General Public License 2.0 (GPL) Only"
2525N/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.
2525N/A must-accept 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
2525N/A considered equivalent to "false". The method of
2525N/A acceptance (interactive, configuration-based,
2525N/A etc.) is at the discretion of clients.
2525N/A must-display When "true", the action's payload must be displayed
2525N/A by clients during packaging operations. Omission of
2525N/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
2525N/A The 'license' attribute is the key attribute for the license action.
2525N/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:
2525N/A category The value for the CATEGORY parameter. The default value
2525N/A desc The value for the DESC parameter.
2525N/A hotline The value for the HOTLINE parameter.
2525N/A name The value for the NAME parameter. The default value is
2525N/A pkg The abbreviation for the package being installed. The
2525N/A default value is the name from the package's FMRI.
2525N/A vendor The value for the VENDOR parameter.
2525N/A version The value for the VERSION parameter. The default value is
2525N/A the version from the package's FMRI.
2525N/A The 'pkg' attribute is the key attribute for the legacy action.
2525N/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:
2525N/A name The name of the attribute.
2525N/A value 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.
2525N/A to classify the package. The value should have
2525N/A separated by a colon (:). The first is used
2525N/A functionality of the package, typically a
2525N/A obsolete package may have no actions other than
2525N/A more set actions, and must not be marked renamed.
2525N/A There must be one or more "depend" actions in
2525N/A the package as well which point to the package
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
2525N/Aself-contained archive file.
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.