Standards, Environments, and Macros pkg(5)NAMEpkg - image packaging system
DESCRIPTION
The image packaging system, pkg(5), is a framework which provides for
software lifecycle management (installation, upgrade, and removal).
Image packaging manages software in units of packages, which are
collections of 'actions', defined by a set of key/value pairs and
possibly a data payload. In many cases, actions are files found in
a filesystem, but they also represent other installable objects,
such as drivers, services, and users.
Package FMRIs and Versions
Each package is represented by a fault management resource identifier
(FMRI) with the scheme 'pkg:'. The full FMRI for a package consists
of the scheme, a publisher, the package name, and a version string in
the following format:
pkg://opensolaris.org/library/libc@5.11,5.11-0.75:20071001T163427Z
'opensolaris.org' is the publisher. 'library/libc' is the package
name. Although the namespace is hierarchical and arbitrarily deep,
there is no enforced containment -- the name is essentially arbitrary.
A publisher's identifying name is a forward domain name that can be used
to identify a person, group of persons, or an organization as the source
of one or more packages. A publisher name should be constructed from an
Internet domain name that is owned, managed, or represented by or on
behalf of a publisher. Other constructions may lead to collisions and be
unsafe for general use.
The version follows the package name, separated by an '@'. It
consists of four sequences of numbers, separated by punctuation. The
elements in the first three sequences are separated by dots, and the
sequences are arbitrarily long.
The first part is the component version. For components tightly bound
to OpenSolaris, this will usually be the value of 'uname -r' for that
version of OpenSolaris. For a component with its own development
lifecycle, this sequence will be the dotted release number, such as
'2.4.10'.
The second part, following the comma, is the build version, specifying
what version of OpenSolaris the contents of the package were built on,
providing a minimum bound on which OpenSolaris version the contents can be
expected to run successfully.
The third part, following the dash, is the branch version, a
versioning component, providing vendor-specific information. This may
be incremented when the packaging metadata is changed, independently
of the component, may contain a build number, or some other
information.
The fourth part, following the colon, is a timestamp. It represents
when the package was published.
Many parts of the system, when appropriate, will contract FMRIs when
displaying them to reduce the volume of information provided.
Typically, the scheme, publisher, build version, and timestamp will be
elided, and sometimes the versioning information altogether.
Actions
Actions represent the installable objects on a system. They are
described in a package's manifest. Every action consists primarily of
its name and a key attribute. Together, these refer to a unique
object as it follows a version history. Actions may have other
attributes. Some of these will be interpreted directly by the
packaging system, others may be useful only to the system
administrator or the end-user.
The attributes listed below are not an exhaustive set; indeed, the
attributes which may be attached to an action are arbitrary, and
indeed, the standard sets are easily augmented to incorporate future
developments.
Certain action attributes cause additional operations to be
executed outside of the packaging context. These are documented
below, under the topic "Actuators".
File Actions
The 'file' action is perhaps the most common action, and represents an
'ordinary file'. It references a payload, and has four standard
attributes:
path The filesystem path where the file is installed. This is a
file action's key attribute.
mode The access permissions (in numeric form) of the file. These
are simple permissions only, not ACLs.
owner The name of the user which owns the file.
group The name of the group which owns the file.
Other attributes include:
preserve This specifies that the file's contents should not be
overwritten on upgrade if they are determined to have
changed since it was installed or last upgraded.
If the value of this attribute is 'renameold', then the
existing file will be renamed, and the new file will be put
in its place.
If the value of this attribute is 'renamenew', then the
existing file will be left alone, and the new file will be
installed with a new name.
If the value of this attribute is 'strawberry', then the
existing file will be left alone, and the new file will not
be installed.
Files may also be 'tasted', and depending on the flavor, may have
additional interesting attributes. For ELF files, the following
attributes are recognized:
elfarch The architecture of the ELF file. This will be the output of
'uname -p' on the architecture for which the file is built.
elfbits This will be '32' or '64'.
elfhash This is the hash of the 'interesting' ELF sections in
the file. These are the sections that are mapped into
memory when the binary is loaded, and are the only ones
necessary to consider when determining whether two
binaries' executable behavior will differ.
original_name This attribute is used to handle editable files moving
from package to package or from place to place, or both.
The form this takes is the name of the originating package,
followed by a colon and the original path to the file.
Any file being deleted is recorded either with its
package and path, or with the value of the original_name
attribute if specified. Any editable file being installed
that has the original_name attribute set will use the
file of that name if it is deleted as part of the same
packaging operation.
Directory Actions
The 'dir' action is like the file action in that it represents a
filesystem object, but a directory instead of an ordinary file. It
has the same four standard attributes as the file action, and 'path'
is the key attribute.
If a package operation triggers a directory removal, the client can
take two possible actions. It will either preserve the directory,
or will move its contents into $IMAGE_META/lost+found. See FILES
for more information about $IMAGE_META. Directory removal
typically occurs during an uninstall operation, but it may also
occur during an update from one version to another.
Link Actions
The 'link' action represents a symbolic link. It has two standard
attributes:
path The filesystem path where the symlink is installed. This is a
link action's key attribute.
target The target of the symlink; the filesystem object to which the
link resolves.
Hardlink actions
The 'hardlink' action represents a hard link. It has the same
attributes as the link action, and 'path' is also its key attribute.
Driver actions
The 'driver' action represents a device driver. It 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):
name The name of the driver. This is usually, but not always,
the filename of the driver binary. This is the driver
action's key attribute.
alias This represents an alias for the driver. There may be
more than one alias attribute for any given driver.
There are no special quoting rules necessary.
class This represents a driver class. There may be more than
one class attribute for any given driver.
perms This represents the filesystem permissions for the
driver's device nodes.
clone_perms This represents the filesystem permissions for the
"clone" driver's minor nodes for this driver.
policy This specifies additional security policy for the device.
There may be more than one policy attribute for any given
driver, but no minor device specification may be present in
more than one attribute.
privs This specifies privileges used by the driver. There may
be more than one privs attribute for any given driver.
devlink This specifies an entry in /etc/devlink.tab. The value
is the exact line to go into the file, with tabs denoted
by "\t". See devlinks(1M) for more information. There
may be more than one devlink attribute for any given
driver.
Depend actions
The 'depend' action represents an inter-package dependency. A package
may 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 may be optional.
The following attributes are recognized:
type The type of the dependency. If the value is 'require', then the
dependency is required. A package cannot be installed if any of
its required dependencies cannot be satisfied.
If the value is 'optional', then the dependency is optional.
Optional dependencies are followed or not depending on image
policy (see 'Policy' below).
If the value is 'exclude', then the package is non-functional if
the dependent package is present on the system.
If the value is 'incorporate', then the dependency is
optional, but the version of the dependent package will
become constrained. See 'Constraints and Freezing' below.
fmri The FMRI representing the depended-upon package.
There is no key attribute for depend actions.
License actions
The 'license' action represents a license or other informational
file associated with the package contents. A package may deliver
licenses, disclaimers, or other guidance to the package installer
through the use of the license action.
The payload of the license action will be delivered into the image
metadata directory related to the package, and should only contain
human-readable textual data. It should not contain HTML or any
other form of markup. License actions, through attributes, may
indicate to clients that the related payload must be displayed
and/or require "acceptance" of it. Please note that the exact
method of display and/or acceptance is at the discretion of
clients.
The following attributes are recognized:
license 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 might 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. This value must be unique within a package.
must-accept When "true", this license must be accepted by a
user before the related package can be installed
or updated. Omission of this attribute will be
considered equivalent to "false". The method of
acceptance (interactive, configuration-based,
etc.) is at the discretion of clients.
must-display 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
clients.
The 'license' attribute is the key attribute for the license action.
Legacy actions
The 'legacy' action represents package data used by a legacy
packaging system. The attributes associated with this action are
added into the legacy system's databases in order that the tools
querying those databases might 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 it may be used to
satisfy dependencies.
The following attributes, named in accordance with the parameters on
pkginfo(4), are recognized:
category The value for the CATEGORY parameter. The default value
is "system".
desc The value for the DESC parameter.
hotline The value for the HOTLINE parameter.
name The value for the NAME parameter. The default value is
"none provided".
pkg The abbreviation for the package being installed. The
default value is the name from the package's FMRI.
vendor The value for the VENDOR parameter.
version The value for the VERSION parameter. The default value is
the version from the package's FMRI.
The 'pkg' attribute is the key attribute for the legacy action.
Set actions
The 'set' action represents a package-level attribute, or metadata,
such as the package description.
The following attributes are recognized:
name The name of the attribute.
value The value given to the attribute.
The set action can deliver any metadata the package author chooses;
however, there are a number of well-defined attribute names which have
specific meaning to the packaging system.
info.classification One or more tokens which a pkg(5) client may use
to classify the package. The value should have
a scheme (such as "org.opensolaris.category.2008"
or "org.acm.class.1998") and the actual
classification, such as "Applications/Games",
separated by a colon (:).
pkg.description A detailed description of the contents and
functionality of the package, typically a
paragraph or so in length.
pkg.obsolete When "true", the package is marked obsolete. An
obsolete package may have no actions other than
more set actions, and must not be marked renamed.
pkg.renamed When "true", the package has been renamed.
There must be one or more "depend" actions in
the package as well which point to the package
versions to which this package has been renamed.
A package may not be marked both renamed and
obsolete, but otherwise may have any number of
set actions.
pkg.summary A short, one-line description of the package.
Group actions
The 'group' action defines a Unix group as defined in group(4).
No support is present for group passwords. Groups defined with
this action initially have no user-list; users may be added with
the 'user' action. The following attributes are recognized:
groupname The value for the name of the group.
gid The groups unique numerical id. The default value is the first
free group under 100.
User actions
The 'user' action defines a Unix user as defined in /etc/passwd, /etc/shadow,
/etc/group and /etc/ftpd/ftpusers files. Users defined with this attribute
have entries added to the appropriate files.
The following attributes are recognized:
username The unique name of the user
password The encrypted password of the user. Default value is '*LK*'.
See shadow(4).
uid The unique uid of the user. Default value is first free value
under 100.
group The name of the users primary group. Must be
found in /etc/group
gcos-field The value of the gecos field in /etc/passwd. Default value is
username.
home-dir The user's home directory. Default value is '/'.
login-shell The user's default shell. Default value is empty.
group-list secondary groups to which the user belongs. See group(4).
ftpuser Can be set to "true" or "false". The default value
of "true" indicates that the user is permitted to
login via FTP. See ftpusers(4).
lastchng The number of days between January 1, 1970, and
the date that the password was last modified.
Default value is empty. See shadow(4).
min The minimum number of days required between
password changes. This field must be set to 0 or
above to enable password aging. Default value is
empty. See shadow(4).
max The maximum number of days the password is
valid. Default value is empty. See shadow(4).
warn The number of days before password expires that
the user is warned. See shadow(4).
inactive The number of days of inactivity allowed for
that user. This is counted on a per-machine
basis; the information about the last login is
taken from the machine's lastlog file. See
shadow(4).
expire An absolute date expressed as the number of days
since the Unix Epoch (January 1, 1970). When
this number is reached the login can no longer
be used. For example, an expire value of 13514
specifies a login expiration of January 1, 2007.
See shadow(4).
flag set to empty. See shadow(4).
Actuators
In certain contexts, additional operations may be appropriate to
execute in preparation for or following the introduction of a
particular action. These additional operations are generally
needed only on a live system image, and are operating
system-specific. When multiple actions involved in a package
installation or removal have identical actuators, then the
operation corresponding to actuator presence is executed once for
that installation or removal.
Incorrectly specified actuators may result in package installation
failure, if the actuator cannot determine a means of making
safe installation progress.
The following actuators are defined:
reboot-needed Can be set to "true" or "false". If an action
with this actuator set to "true" is installed or
updated during a package installation, then the
packaging transaction can be advertised as requiring a
reboot. Certain client implementations may take
additional steps, such as performing the entire package
operation using a clone of the image, in the case that
the image is the live system image.
disable_fmri
refresh_fmri
restart_fmri
suspend_fmri Each of these actuators take the value of an FMRI of
a service instance to operate upon during the package
installation or removal. disable_fmri causes the
mentioned FMRI to be disabled prior to action removal, per
the disable subcommand to svcadm(1M). refresh_fmri and
restart_fmri cause the given FMRI to be refreshed or
restarted after action installation or update, per the
respective subcommands of svcadm(1M). Finally,
suspend_fmri causes the given FMRI to be disabled
temporarily prior to the action install phase, and then
enabled after the completion of that phase.
The value may contain a pattern matching multiple service
instances. However, it must do so explicitly with a glob
as accepted by svcs(1), rather than doing so implicitly by
not indicating any instances.
Constraints and Freezing
TBD
Client-Server Operation
TBD
Publishers and Mirroring
TBD
Images and Substrates
TBD
Properties
Images can have one or more properties associated with them.
These properties can be used to store information about the purpose,
content and behavior of the image.
Image Policies
Policies are defined by image properties with boolean values. The
supported policies include:
flush-content-cache-on-success
When true, the cache of downloaded files is erased after a
successful install of a package. Default value: False.
send-uuid
When true, a unique identifier (UUID) that identifies the
image to the publisher is sent on all requests. Default
value: True.
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | SUNWipkg |
| | pkg:/package/pkg |
|_____________________________|_____________________________|
| Interface Stability | None / Under Development |
|_____________________________|_____________________________|
FILES
Since pkg(5) images can be located arbitrarily within a larger file
system, we use the token $IMAGE_ROOT to distinguish relative paths.
For a typical system installation, $IMAGE_ROOT is equivalent to
"/".
$IMAGE_ROOT/var/pkg
Metadata directory for a full or partial image.
$IMAGE_ROOT/.org.opensolaris,pkg
Metadata directory for a user image.
Within a particular image's metadata, certain files and directories
can contain information useful during repair and recovery. We use
the token $IMAGE_META to refer to the top-level directory
containing the metadata. $IMAGE_META is typically one of the two
paths given above.
$IMAGE_META/lost+found
Location of conflicting directories and files moved during a
package operation.
$IMAGE_META/publisher
Contains a directory for each publisher. Each directory stores
publisher-specific metadata.
Other paths within the $IMAGE_META directory hierarchy are Private,
and are subject to change.
SEE ALSOpkg(1), pkgsend(1), pkg.depotd(1M), svcadm(1M), pkginfo(4),
attributes(5)NOTES
The image packaging system is an under-development feature.
Command names, invocation, formats, and operations are all subject
to change. Development is hosted in the OpenSolaris community
at
http://hub.opensolaris.org/bin/view/Project+pkg/
