Source code file content
17477111 resync manpages from docs group
Size: 39136 bytes, 1 line
.. CDDL HEADER START
.. The contents of this file are subject to the terms of the
Common Development and Distribution License (the "License").
You may not use this file except in compliance with the License.
.. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
See the License for the specific language governing permissions
and limitations under the License.
.. When distributing Covered Code, include this CDDL HEADER in each
file and include the License file at usr/src/OPENSOLARIS.LICENSE.
If applicable, add the following below this CDDL HEADER, with the
fields enclosed by brackets "" replaced with your own identifying
information: Portions Copyright [yyyy] [name of copyright owner]
.. CDDL HEADER END
.. Copyright (c) 2011, Oracle and/or its affiliates. All rights reserved.
This chapter defines IPS terms and describes the 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. Images
are of three types:
in a full image, all dependencies are resolved within the
image itself and IPS maintains the dependencies in a consistent
in a zone image, IPS maintains the zone consistent with its
global zone as defined by dependencies in the packages;
not yet fully functional for Oracle Solaris.
In general, images are created or cloned by other software (installers,
|beadm|, |zonecfg|, etc) rather than directly by the user.
IPS deals with all software installed on a system in the granularity of
packages. Every package is represented by a *fault management resource
identifier* (FMRI), consisting of a publisher, a name, and a version, with
the scheme ‘``pkg``’. For example::
Here, ‘``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.
Package names are hierarchical with an arbitrary number of components
separated by forward slash (‘``/``’) characters. 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. Package name components are case
sensitive and must start with a letter or number, but can include
underscores (‘``_``’), dashes (‘``-``’), periods (‘``.``’), and plus signs
(‘``+``’) in later positions.
FMRIs can appear and can be referred to in abbreviated form. The scheme
is typically unnecessary, leaving the FMRI to start with either a double
slash (‘``//``’) or a single slash (‘``/``’). When the first slash is
doubled, the first word following the slash is the publisher name. When
there is only a single leading slash, no publisher name is present, and the
package name is considered complete, or ‘rooted’.
Further abbreviation is possible by eliding leading components of package
names. For instance, ``/driver/network/ethernet/e1000g`` can be reduced to
``network/ethernet/e1000g``, ``ethernet/e1000g``, or even simply
``e1000g``. Note that such abbreviation mighy cause the packaging client to
complain about ambiguous package names, in which case disambiguation can
always be achieved by specifying the full, rooted name. Typically package
names are chosen to reduce possible ambiguities, even when referred to
solely by their last component. Some trailing components are common,
however; in such cases, the last two components should be unambiguous.
Scripts should generally refer to packages by their full, rooted names.
It is not possible to construct an abbreviated FMRI that contains a
publisher name and only trailing package name components.
The version is also often unnecessary; packages referred to without version
will generally resolve to the latest version of the package that can be
installed. As explained below, versions themselves need not be complete.
FMRIs can also be referred to with patterns, where an asterisk (‘``*``’)
can match any portion of a package name. Thus ``/driver/*/e1000g`` will
expand to ``/driver/network/ethernet/e1000g``, as will ``/dri*00g``.
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 components (e.g. ‘``01.1``’ or ‘``1.01``’) are
forbidden, to allow for unambiguous sorting by package version.
An example version is::
The first part is the component version. For components that are
are developed as part of Oracle Solaris, this will represent 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 part, which if present must follow a comma, is the build
version. Oracle Solaris uses this to denote the release of the OS for
which the package was compiled.
The third part, which if present must follow a dash, is the branch version,
providing vendor-specific information. This can be incremented when the
packaging metadata is changed, independently of the component; can contain
a build number; or provide some other information.
The fourth part, which if present must follow a colon, is a timestamp.
It represents when the package was published in the GMT timezone, and is
automatically updated when the package is published.
The package versions are ordered using left-to-right precedence; thus
the timestamp is the least significant part of the version space; the
number immediately after the ‘``@``’ is the most significant.
If required, ``pkg.human-version`` 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, and is documented later in this chapter.
By allowing arbitrary version lengths, IPS can accommodate a variety
of different models for supporting software. Within the confines
of a given component version, a package author can use the build or branch
versions and assign one portion of the versioning scheme to security
updates, another for paid vs. unpaid support updates, another for minor bug
A version can also be the token ‘``latest``’, which is substituted for the
latest version known.
We discuss how Oracle Solaris implements versioning in *Chapter 13*.
A publisher is an entity that develops and constructs packages. A
publisher name, or prefix, is used to identify this source in a unique
manner. The use of Internet domains or registered trademarks is
encouraged, since it provides a natural namespace partitioning.
Package clients combine all specified sources of packages for a given
publisher when computing packaging solutions. Publisher names can
include upper and lower case letters, numbers, dashes and periods; the same
characters as a valid hostname.
.. raw:: pdf
Actions are used to define the software that comprises a package; they
define the data needed to create this software component. When creating
packages, the developer expresses the package contents as a set of actions
then saves those to a *package manifest* file.
Actions look like this:
*action_name* *attribute1*\=\ *value1* *attribute2*\=\ *value2* ...
As a concrete example::
dir path=a/b/c group=sys mode=0755 owner=root
The first field identifies this as a ``dir`` (or directory) action; the
``name=value`` attributes describe the familiar properties of that
directory. In the cases where the action has data associated with it,
such as a file, the action looks like this::
file 11dfc625cf4b266aaa9a77a73c23f5525220a0ef path=etc/release owner=root \
group=sys mode=0444 chash=099953b6a315dc44f33bca742619c636cdac3ed6 \
pkg.csize=139 pkg.size=189 variant.arch=i386
Here the second attribute (without a ``name=`` prefix), called the
payload, is the SHA-1 hash of the file. This attribute can alternatively
appear as a regular attribute with the name ``hash``; if both forms are
present they must have the same value.
Action metadata is freely extensible; additional attributes can be
added to actions as desired. Attribute names cannot include spaces,
quotes, or equals signs (‘``=``’). Attribute values can have all of those,
although values with spaces must be enclosed in single or double quotes. Single
quotes need not be escaped inside of a double-quoted string, and vice
versa, though a quote can be prefixed with a backslash (‘``\``’) so as not
to terminate the quoted string. Backslashes can be escaped with
backslashes. It is recommended that custom attributes use a reverse
domain name or similar unique prefix to prevent accidental namespace
Multiple attributes with the same name can be present and are
treated as unordered lists.
Note that manifests are largely created using programs; it is not
expected that that developers produce complete manifests by hand, but
rather create skeletons with the minimal non-redundant information, and
have the rest filled in with tools such as |pkgmogrify| and |pkgdepend|.
Most actions have key attributes; this attribute is what makes this
action unique from all others in the image. For file system
objects, this is the path for that object.
Types of Actions
There are currently twelve action types in IPS. The following
sections describe each action type, and the attributes that
define these actions. The action types are detailed in the |pkg5| man
page, and are repeated here for reference.
Each section contains an example action, as it would appear in a 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, and represents an
‘ordinary file’. The file action references a payload, and has four
The file system path where the file is installed.
This is a file action's key attribute. These are relative
to the root of the image.
The access permissions (in numeric form) of the
file. These are simple permissions only, not ACLs.
The name of the user that owns the file.
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|. 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.
Other attributes include:
This specifies that the file's contents 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, the file
is salvaged (stored in ``/var/pkg/lost+found``).
* If the value of ``preserve`` is ``renameold``, then the
existing file is renamed with the extension
``.old``, and the new file is put in its place.
* If the value of ``preserve`` is ``renamenew``, then the
existing file is left alone, and the new file is
installed with the extension ``.new``.
* If the value of ``preserve`` is ``legacy``, then 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.
* If the value of ``preserve`` is ``true`` (or a value not
listed above, such as ``strawberry``), then the
existing file is left alone, and the new file is
not installed. Other values with specific meanings might
be added in future, so using ``true`` should be used if
this functionality is required.
This 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.
* If the value of ``overlay`` is ``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.
* If the value of ``overlay`` is ``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.
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
Note that once set, this attribute should never
change even if the package or file are repeatedly renamed;
this will permit upgrade to occur from all previous versions.
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 ``pkg revert`` is invoked
with any of those tags specified. See
Specific types of file can have additional attributes. For ELF files,
the following attributes are recognized:
The architecture of the ELF file. This will is the output of
``uname -p`` on the architecture for which the file is built.
This is ``32`` or ``64``.
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
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``.
To move unpackaged contents into a new directory, the following
attribute might be useful:
This names a directory of salvaged items. A
directory with such an attribute inherits on
creation the salvaged directory contents if
During installation, |pkg| will check that all instances of a given
directory action on the system have the same owner, group and mode
attributes, and will not install the action if conflicting actions
will exist on the system as a result of the 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 a ``link`` action's key attribute.
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 *Chapter 10*.
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.
However, there are a number of well-defined attribute names that have
specific meaning to the packaging system.
The name and version of the containing package.
One or more tokens that a |pkg5| 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| GUI. A set of
``info.classification`` values is included in
A brief synopsis of the description. This is
output with ``pkg list -s`` at the end of each
line, as well as in one line of the output of
``pkg info``, so it should be no longer than
sixty characters. It should describe *what* a
package is, and should refrain from repeating
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. It should describe
*why* someone might want to install the 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 *Chapter 10*
When ``true``, the package has been renamed.
There must be one or more ``depend`` actions in
the package 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
The version scheme used by IPS is strict, and
does not allow for letters or words in the
``pkg.fmri`` version field. If there is a commonly
used human-readable version available for a given
package, that can be set here, and is displayed
by IPS tools. It does not get 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 *Chapter 13*.
An example of a ``set`` action is::
set name=pkg.summary value="Image Packaging System"
.. raw:: pdf
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):
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
This represents an alias for the driver. A
given driver can have more than one ``alias``
attribute. No special quoting rules are
This represents a driver class. A given
driver can have more than one ``class`` attribute.
This represents the file system permissions
for the driver's device nodes.
This represents the file system permissions
for the clone driver's minor nodes for this
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
This specifies privileges used by the driver.
A given driver can have more than one ``privs``
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(1M)`` for more information. A given
driver can have more than one ``devlink``
An example of a driver action is::
driver name=vgatext \
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 more detail in *Chapter 6*.
The following attributes are recognized:
The FMRI representing the target of the dependency. This is the
dependency action’s key attribute. 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
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
The FMRI value cannot use asterisks, and cannot use the
``latest`` token for a version.
The type of the dependency.
* If the value is ``require``, then 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
required dependencies cannot be satisfied.
* If the value is ``optional``, then the target, if present, must
be at the specified version level or greater.
* If the value is ``exclude``, then the containing package cannot
be installed if the 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.
* If the value is ``incorporate``, then the dependency is
optional, but the version of the target package is
constrained. See *Chapter 6* for a discussion of
constraints and freezing.
* If the value is ``require-any``, then any one of multiple target
packages as specified by multiple ``fmri`` attributes can satisfy
the dependency, following the same rules as the ``require``
* If the value is ``conditional``, the target is required
only if the package defined by the ``predicate`` attribute is present
on the system.
* If the value is ``origin``, the target must, if present,
be at the specified value or better on the image to be modified
prior to installation. 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.
* If the value is ``group``, the 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| man page.
* If the value is ``parent``, then 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 target is required to be present
in the parent image. The version matching for a ``parent``
dependency is the same as that used for ``incorporate``
The FMRI representing the predicate for ``conditional``
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 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:
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
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 action's payload must be displayed
by clients during packaging operations. Omission of
this value is considered equivalent to ``false``.
This attribute should not be used for copyright
notices, only actual licenses or other material
that must be displayed during operations. The
method of display is at the discretion of
The ``license`` attribute is the key attribute for the license action.
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 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 SVR4 dependencies.
The following attributes, named in accordance with the parameters in
|pkginfo|, are recognized:
The value for the CATEGORY parameter. The default value
The value for the DESC parameter.
The value for the HOTLINE parameter.
The value for the NAME parameter. The default value is
The abbreviation for the package being installed. The
default value is the name from the FMRI of the package.
The value for the VENDOR parameter.
The value for the VERSION parameter. The default value is
the version from the FMRI of the package.
The ``pkg`` attribute is the key attribute for the legacy action.
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" \
Signature actions are used as part of the support for package signing in
IPS. They are covered in detail in *Chapter 11*.
The user action defines a UNIX user as defined in ``/etc/passwd``,
``/etc/shadow``, ``/etc/group``, and ``/etc/ftpd/ftpusers`` files.
Users defined with this action have entries added to the
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 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
Secondary groups to which the user belongs.
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)``.
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 ``shadow(4)``.
The number of days before password expires
that the user is warned.
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.
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.
For more information on the values of these attributes, see
the ``shadow(4)`` man page.
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 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
The value for the name of the group.
The group's unique numeric id. 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 *Chapter 4*.
A repository accessed via HTTP or HTTPS has a server process (|pkg.depotd|)
associated with it; in the case of file repositories, the repository
software runs as part of the accessing client.
Repositories are created with the |pkgrepo| command, and package archives
are created with the |pkgrecv| command.