svcadm(1M)을 검색하려면 섹션에서 1M 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
pkg(7)
Standards, Environments, Macros, Character Sets, and miscellany
pkg(7)
NAME
pkg - Image Packaging System
DESCRIPTION
The Image Packaging System, pkg(7), is a framework that provides for
software lifecycle management (installation, upgrade, and removal).
Image packaging manages software in units of packages, which are col‐
lections of actions, defined by a set of key/value pairs and possibly a
data payload. In many cases, actions are files found in a file system,
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://solaris/system/library/c++-runtime@11.4-11.4.0.0.1.1.2:20170919T184404Z
solaris is the publisher. system/library/c++-runtime is the package
name. Although the namespace is hierarchical and arbitrarily deep,
there is no enforced containment; the name is arbitrary. The publisher
information is optional, but must be preceded by pkg:// if present. An
FMRI that includes the publisher is often referred to as being "fully
qualified." If publisher information is not present, then the package
name should generally be preceded by pkg:/.
Packaging clients often allow the scheme of an FMRI to be omitted if it
does not contain publisher information. For example, pkg:/sys‐
tem/library/c++-runtime can be written as system/library/c++-runtime.
If the scheme is omitted, clients also allow omission of all but the
last component of a package name for matching purposes. For example,
system/library/c++-runtime could be written as library/c++-runtime or
c++-runtime, which would then match packages named c++-runtime or pack‐
age names ending in /c++-runtime.
A publisher name identifies a person, group of persons, or an organiza‐
tion as the source of one or more packages. To avoid publisher name
collisions and help identify the publisher, a best practice is to use a
domain name that represents the entity publishing the packages as a
publisher name.
The version follows the package name, separated by an at (@) sign. The
version consists of a component version, a branch version, and a time‐
stamp. The component version and branch version are separated by a
hyphen (-). The branch version and timestamp are separated by a colon
(:). Leading zeros (for example, 01.1 or 1.01) are not permitted in
elements of the component version or branch version. Trailing zeros
(for example, 1.10) are permitted.
Component version: 11.4. For components tightly bound to the operating
system, the component version number is minor.update. Components with
their own development lifecycle, such as FOSS components, have their
own version numbers, such as 2.4.10. The component version can be arbi‐
trarily long.
Branch version: 11.4.0.0.1.1.2. The branch version, if present, must
follow a hyphen (-). The branch version string is the same as the
"Branch" in pkg info output.
Oracle Solaris packages show the following information in the branch
version portion of the version string of a package FMRI:
minor.update.sru.order.platform.build.rev
Minor release number: 11
The minor portion of major.minor that is output by the uname -r.
Update release number: 4
The update release number for this Oracle Solaris release.
SRU number: 0
The Support Repository Update (SRU) number for this update release.
SRUs are approximately monthly updates that fix bugs, fix security
issues, or provide support for new hardware. The Oracle Support
Repository is available only to systems under a support contract.
Order: 0
This value is used internally.
Platform: 1
This value is used internally.
Release or SRU build number: 1
The build number of the SRU, or the respin number for the release.
Revision or nightly build number: 2
The build number for the individual nightly builds.
If the package is an Interim Diagnostic or Relief (IDR) update, then
the branch version of the package FMRI contains the following two addi‐
tional fields. IDRs are package updates that help diagnose customer
issues or provide temporary relief for a problem until a formal package
update is issued. The following examples are for idr824, which has FMRI
pkg://solaris/idr824@4,5.11:20131114T034951Z and contains packages such
as pkg://solaris/system/library@11.4-11.4.0.0.1.1.2.824.4:
IDR: 824
The name of the IDR.
IDR ID: 4
The version of the IDR.
Timestamp: 20170919T184404Z. The timestamp must follow a colon (:). The
timestamp is the time the package was published in ISO-8601 basic for‐
mat: YYYYMMDDTHHMMSSZ.
When performing comparisons between versions, no component of the full
version is considered unless the components to its left are the same.
Thus, 4.3-1 is greater than 4.2-7 because 4.3 is greater than 4.2, and
4.3-3 is greater than 4.3-1 because 3 is greater than 1.
The pkg.human-version attribute can be used to provide a human-readable
version string. The value of the pkg.human-version attribute can be
provided in addition to the package version described above for the
package FMRI but cannot replace the package FMRI version. The human-
readable version string is only used for display purposes. See "Set
Actions" for more information.
Many parts of the system, when appropriate, abridge FMRIs when display‐
ing them, and accept input in shorter forms to reduce the volume of
information displayed or required. Typically, the scheme, publisher,
build version, and timestamp can be elided. Sometimes all of the ver‐
sioning information can be omitted.
ACTIONS
Actions represent the installable objects on a system. Actions are
described in the manifest of a package.
To remove a file or other installable object from the image, remove the
associated action from the package manifest. The object will be removed
from the image when the package is updated by using the pkg update com‐
mand. For more information, see Packaging and Delivering Software With
the Image Packaging System in Oracle Solaris 11.4.
Every action consists primarily of its name and a key attribute.
Together, these refer to a unique object as it follows a version his‐
tory. Actions can have other attributes. Some attributes are inter‐
preted directly by the packaging system. Other attributes might be use‐
ful only to the system administrator or the end-user.
Actions have a simple text representation:
action_name attribute1=value1 attribute2=value2 ...
Names of attributes cannot have whitespace, quotation marks, or equals
signs (=) in them. All characters after the first equals sign belong to
the value. Values can have all of those, though spaces must be enclosed
in single or double quotation marks. Single quotation marks do not need
to be escaped inside a string that is enclosed in double quotation
marks, and double quotation marks do not need to be escaped inside a
string that is enclosed in single quotation marks. A quotation mark can
be prefixed with a backslash (\) character to avoid terminating the
quoted string. A backslash can be escaped with a backslash.
Actions can have multiple attributes. Some attributes can be named mul‐
tiple times with different values for a single action. Multiple
attributes with the same name are treated as unordered lists.
Actions with many attributes can create long lines in a manifest file.
Such lines can be wrapped by terminating each incomplete line with a
backslash. Note that this continuation character must occur between
attribute/value pairs. Neither attributes nor their values nor the com‐
bination can be split.
The attributes listed below are not an exhaustive set. In fact, the
attributes that can be attached to an action are arbitrary, and the
standard sets of attributes are easy to augment to incorporate future
developments.
Some attributes cause additional operations to be executed outside of
the packaging context. These attributes are documented in the "Actua‐
tors" section below.
Actions that are installed to a path must not deliver content to any of
the following paths:
/system/volatile
/tmp
/var/share
/var/tmp
Additionallly, the following directories are reserved for use by the
system and should also not be used by actions:
/var/pkg
File Actions
The file action represents an ordinary file. The file action references
a payload, and has four standard attributes:
path The file system 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 that owns the file.
group 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(1). 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.
The preserve and overlay attributes affect whether and how a file
action is installed.
preserve
Specifies when and how files are preserved during package opera‐
tions.
When a package is initially installed, if a file delivered by the
package has a preserve attribute defined with any value except
abandon or install-only and the file already exists in the image,
the existing file is stored in /var/pkg/lost+found and the packaged
file is installed.
When a package is initially installed, if a file delivered by the
package has a preserve attribute defined and the file does not
already exist in the image, whether that file is installed depends
on the value of the preserve attribute:
o If the value of preserve is abandon or legacy, the pack‐
aged file is not installed.
o If the value of preserve is not abandon or legacy, the
packaged file is installed.
When a package is downgraded, if a file delivered by the downgraded
version of the package has a preserve attribute defined with any
value except abandon or install-only and all of the following con‐
ditions are true, the file that currently exists in the image is
renamed with the extension .update, and the file from the down‐
graded package is installed.
o The file exists in the image.
o The content of the file delivered by the downgraded ver‐
sion of the package is different from the content of the
file delivered by the currently installed version of the
package.
o The content of the file delivered by the downgraded ver‐
sion of the package is different from the content of the
file that exists in the image.
If any of the above conditions is not true, the file is treated the
same as if the package is being upgraded, rather than downgraded.
When a package is upgraded, if a file action delivered by the
upgraded version of the package has a preserve attribute defined
with any value and the file action is the same as the file action
delivered by the currently installed version of the package, the
file is not installed, and the file that exists in the image is not
modified. Any modifications made since the previous version was
installed are preserved.
When a package is upgraded, if a file action delivered by the
upgraded version of the package has a preserve attribute defined
and the file action is new or is different from the file action
delivered by the currently installed version of the package, the
upgrade is done in the following way:
o If the file delivered by the upgraded version of the
package has a preserve value of abandon or install-only
in the upgraded package, the new file will not be
installed and the existing file will not be modified.
o If the file delivered by the package has a preserve
value of abandon then any attempt to revert the file
will not restore the file. Any revert-tag associated
with the file will be ignored.
o If the file does not exist in the image, the new file is
installed.
o If the file delivered by the upgraded version of the
package exists in the image, did not exist in the cur‐
rently installed version of the package, and was not
renamed or moved by using the original_name attribute
(see below), then the existing file is stored in
/var/pkg/lost+found and the file delivered by the
upgraded version of the package is installed.
o If the file delivered by the upgraded version of the
package exists in the image and has different content
from the file delivered by the currently installed ver‐
sion of the package, the upgrade is done according to
the value of the preserve attribute:
o If the file delivered by the upgraded version of the
package has a preserve value of renameold, the
existing file is renamed with the extension .old,
and the new file is installed with updated permis‐
sions and timestamp (if present). See the timestamp
attribute description below.
o If the file delivered by the upgraded version of the
package has a preserve value of renamenew, the new
file is installed with the extension .new and the
existing file is not modified.
o If the file delivered by the upgraded version of the
package has a preserve value of true, the new file
is not installed, but the permissions and timestamp
(if present) are reset on the existing file.
o If the file delivered by the upgraded version of the
package exists in the image, has the same content as the
file delivered by the currently installed version of the
package, and has a preserve value of either renameold or
renamenew, the existing file is replaced by the file
delivered by the upgraded version of the package,
including replacing permissions and timestamp (if
present).
o If the file delivered by the upgraded version of the
package exists in the image, has a preserve value of
legacy in the upgraded package, and has a different pre‐
serve value in the currently installed version of the
package, the existing file is renamed with the extension
.legacy, and the new file is installed with updated per‐
missions and timestamp (if present).
o If the file delivered by the upgraded version of the
package exists in the image and has a preserve value of
legacy in both the upgraded package and the currently
installed version of the package, the permissions and
timestamp (if present) are reset on the existing file.
Unless otherwise specified above, when a package is downgraded or
upgraded, any file action previously delivered by a package that is
not listed in the new package version is removed from the system.
Additionally, when the package is uninstalled, any file action
delivered by the package is removed.
When a package is uninstalled, if a file action delivered by the
currently installed version of the package has a preserve value of
abandon and the file exists in the image, the file is not removed.
However, any other file action delivered by that package that is
removed, that has a preserve attribute specified, and that has been
modified since it was originally installed is moved to
/var/pkg/lost+found.
overlay
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 file. This functionality is intended for use with
configuration files that do not participate in any self-assembly
(for example, /etc/motd) and that can be safely overwritten.
If overlay is not specified, multiple packages cannot deliver files
to the same location.
The overlay attribute can have one of the following values:
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.
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 con‐
tents 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.
overlay-attributes
Specifies whether image-modifying operations such as install,
update, etc. should report errors when an overlaying action has a
different owner, group, mode or sysattr from its overlaid action.
overlay-attributes is usually used in actions with overlay equal to
allow or deny. When the value of overlay-attributes for either
overlaying action or overlaid action is deny, an error will be gen‐
erated during image-modifying operations. Also verification opera‐
tions will generate an error on those mismatched attributes: owner,
group and mode if overlay is equal to deny for a pair of overlaid
and overlaying action. Otherwise, an info message will be generated
on the above mismatched attributes for the pair. Regardless of the
value of overlay-attributes, mismatched attributes when comparing
the on-disk attributes of a file to its packaged version will
always be reported as errors.
dehydrate
Specifies whether this action should be removed when a package pub‐
lisher's packages are dehydrated or when a dehydrated publisher's
packages are modified. The value of the dehydrate attribute can be
true or false. If the value of the dehydrate attribute is false,
the action will not be removed during dehydrate operations. Other‐
wise, the action will be removed. File actions tagged with the pre‐
serve or overlay attributes are implicitly excluded from dehydra‐
tion operations and do not need this attribute.
file path=etc/zones/SYSdefault.xml dehydrate=false ...
The following attributes are recognized for ELF files:
elfarch
The architecture of the ELF file. This is the output of uname -p on
the architecture for which the file is built.
elfbits
This is 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. These are the only sections necessary to consider when
determining whether the executable behavior of two binaries will
differ.
The following additional attributes are recognized for file actions:
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 origi‐
nal_name attribute if specified. Any editable file being installed
that has the original_name attribute set uses the file of that name
if it is deleted as part of the same packaging operation.
release-note
This attribute is used to indicate that this file contains release
note text. The value of this attribute is a package FMRI. If the
FMRI specifies a package name that is present in the original image
and a version that is newer than the version of the package in the
original image, this file will be part of the release notes. A spe‐
cial FMRI of feature/pkg/self refers to the containing package. If
the version of feature/pkg/self is 0, this file will only be part
of the release notes on initial installation.
revert-tag
This attribute is used to tag editable files that should be
reverted as a set. The value of the revert-tag attribute is a tag‐
name. Multiple revert-tag attributes can be specified for a single
file action. The file reverts to its manifest-defined state when
pkg revert is invoked with any of those tags specified. See the
pkg(1) man page for information about the pkg revert command.
The revert-tag attribute can also be specified at the directory
level. See "Directory Actions" below.
sysattr
This attribute is used to specify any system attributes that should
be set for this file. The value of the sysattr attribute can be a
comma-separated list of verbose system attributes or a string
sequence of compact system attribute options, as shown in the fol‐
lowing examples. Supported system attributes are explained in the
chmod(1) man page. System attributes specified in the manifest are
set additionally to system attributes that might have been set by
other subsystems of the operating system.
file path=opt/secret_file sysattr=hidden,sensitive
file path=opt/secret_file sysattr=HT
timestamp
This attribute is used to set the access and modification time on
the file. The timestamp attribute value must be expressed in UTC in
ISO-8601 format, omitting the colons and hyphens.
The timestamp attribute is essential when packaging .pyc or .pyo
files for Python. The related .py file for the .pyc or .pyo files
must be marked with the timestamp embedded within those files, as
shown in the following example:
file path=usr/lib/python2.7/vendor-packages/pkg/__init__.pyc ...
file path=usr/lib/python2.7/vendor-packages/pkg/__init__.py \
timestamp=20130311T221521Z ...
The following attributes for file actions are automatically generated
by the system and should not be specified by package developers:
hash
The SHA-1 hash of the uncompressed file.
chash
The SHA-1 hash of the compressed file.
pkg.size
The size in bytes of the uncompressed file.
pkg.csize
The size in bytes of the compressed file.
Directory Actions
The dir action is like the file action in that it represents a file
system object. The dir action represents a directory instead of an
ordinary file. The dir action has the same path, mode, owner, and group
attributes that the file action has, and path is the key attribute. The
dir action also accepts the revert-tag attribute. The value of the
revert-tag attribute is different for file and dir actions.
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 $IMAGE_META/lost+found.
See the "Files" section for more information about $IMAGE_META.
revert-tag
This attribute is used to identify unpackaged files that should be
removed as a set. See "File Actions" above for a description of how
to specify this attribute for file actions. For directories, the
value of the revert-tag attribute is tagname=pattern. Multiple
revert-tag attributes can be specified for a single dir action.
When pkg revert is invoked with a matching tagname, any unpackaged
files or directories under this dir directory that match pattern
(using shell globbing characters) are removed. See the pkg(1) man
page for information about the pkg revert command.
salvage-from
This attribute can be used to move unpackaged contents into a new
directory. The value of this attribute is the name of a directory
of salvaged items. A directory with a salvage-from attribute inher‐
its on creation any contents of the directory named in the value of
the salvage-from attribute.
Link Actions
The link action represents a symbolic link. The link action has the
following standard attributes:
path
The file system path where the symbolic link is installed. This is
a link action's key attribute.
target
The target of the symbolic link. The file system object to which
the link resolves.
mediator
Specifies the entry in the mediation namespace shared by all path
names participating in a given mediation group (for example,
python). Link mediation can be performed based on mediator-version
and/or mediator-implementation. All mediated links for a given path
name must specify the same mediator. However, not all mediator ver‐
sions and implementations need to provide a link at a given path.
If a mediation does not provide a link, then the link is removed
when that mediation is selected. A mediator, in combination with a
specific version and/or implementation represents a mediation that
can be selected for use by the packaging system.
mediator-version
Specifies the version (expressed as a dot-separated sequence of
nonnegative integers) of the interface described by the mediator
attribute. This attribute is required if mediator is specified and
mediator-implementation is not. A local system administrator can
set the version to use explicitly. The value specified should gen‐
erally match the version of the package delivering the link (for
example, runtime/python-27 should use mediator-version=2.7),
although this is not required.
mediator-implementation
Specifies the implementation of the mediator for use in addition to
or instead of the mediator-version. Implementation strings are not
considered to be ordered and a string is arbitrary selected by
pkg(7) if not explicitly specified by a system administrator.
The value can be a string of arbitrary length composed of alphanu‐
meric characters and spaces. If the implementation itself can be
versioned or is versioned, then the version should be specified at
the end of the string, after an at (@) sign (expressed as a dot-
separated sequence of nonnegative integers). If multiple versions
of an implementation exist, the default behavior is to select the
implementation with the greatest version.
If only one instance of an implementation mediation link at a par‐
ticular path is installed on a system, then that one is chosen
automatically. If future links at the path are installed, the link
is not switched unless a vendor, site, or local override applies,
or if one of the links is version mediated.
mediator-priority
When resolving conflicts in mediated links, pkg(7) normally chooses
the link with the greatest value of mediator-version or based on
mediator-implementation if that is not possible. This attribute is
used to specify an override for the normal conflict resolution
process.
If this attribute is not specified, the default mediator selection
logic is applied.
If the value is vendor, the link is preferred over those that do
not have a mediator-priority specified.
If the value is site, the link is preferred over those that have a
value of vendor or that do not have a mediator-priority specified.
A local system administrator can override the selection logic
described above.
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. 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(8) for more information):
name
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
attribute.
alias
This represents an alias for the driver. A given driver can have
more than one alias attribute. No special quoting rules are neces‐
sary.
class
This represents a driver class. A given driver can have more than
one class attribute.
perms
This represents the file system permissions for the driver's device
nodes.
clone_perms
This represents the file system permissions for the clone driver's
minor nodes for this driver.
policy
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 attribute.
privs
This specifies privileges used by the driver. A given driver can
have more than one privs attribute.
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(8)
for more information. A given driver can have more than one devlink
attribute.
Depend Actions
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 can be optional. If a dependency is not met at
the time of installation, the packaging system attempts to install or
update the dependent package to a sufficiently new version, subject to
other constraints.
The following attributes are recognized:
fmri
The FMRI representing the dependent package. This is the dependency
action's key attribute. The fmri value must not include the pub‐
lisher. The package name is assumed to be complete. Dependencies of
type group-any and require-any can have multiple fmri attributes. A
version is optional on the fmri value, though for some types of
dependencies, an fmri with no version has no meaning or the version
is ignored.
type
The type of the dependency.
require
The dependency 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 depen‐
dency. A package cannot be installed if any of its required
dependencies cannot be satisfied.
optional
The dependency, if present, must be at the specified version
level or greater.
exclude
The containing package cannot be installed if the dependency is
present at the specified version level or greater. If no ver‐
sion is specified, the dependent package cannot be installed
concurrently with the package specifying the dependency.
incorporate
The dependency is optional, but the version of the dependent
package is constrained. See "Constraints and Freezing" below.
require-any
Any one of the packages specified by multiple fmri attributes
can satisfy the dependency, following the same rules as the
require dependency type.
conditional
The dependency is required only if the package defined by the
predicate attribute is present on the system.
origin
Prior to installation of this package, the dependency target
must, if installed, be at the specified value or greater in the
image to be modified. If the value of the root-image attribute
is true, this applies to the image mounted at / instead.
If the value of the root-image attribute is true and the value
of the fmri attribute starts with pkg:/feature/firmware/, the
remainder of the fmri value is treated as a command in
/usr/lib/fwenum that evaluates the firmware dependency. See
Packaging and Delivering Software With the Image Packaging Sys‐
tem in Oracle Solaris 11.4 for examples.
group
The dependency 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 pkg(1).
group-any
Any one of multiple dependent packages as specified by multiple
fmri attributes can satisfy the dependency, following the same
rules as the group dependency type with the exception that non-
obsolete package stems are preferred over obsolete ones.
parent
The dependency is ignored if the image is not a child image. If
the image is a child image then the dependency is required to
be present in the parent image. The package version matching
for a parent dependency is the same as that used for incorpo‐
rate dependencies.
predicate
The FMRI representing the predicate for conditional dependencies.
root-image
Has an effect only for origin dependencies as mentioned above.
License Actions
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-read‐
able 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:
license
This is a license action's key attribute. This attribute provides a
meaningful description for the license to assist users in determin‐
ing the contents without reading the license text itself. Some
example values include:
o ABC Co. Copyright Notice
o ABC Co. Custom License
o Common Development and Distribution License 1.0 (CDDL)
o GNU General Public License 2.0 (GPL)
o GNU General Public License 2.0 (GPL) Only
o MIT License
o Mozilla Public License 1.1 (MPL)
o Simplified BSD License
The license value must be unique within a package. Including the
version of the license in the description, as shown in several of
the examples above, is recommended. If a package has code under
multiple licenses, use multiple license actions. The length of the
license attribute value should not be more than 64 characters.
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 is equivalent to false. The method of acceptance (inter‐
active or configuration-based, for example) is at the discretion of
clients. For package updates, this attribute is ignored if the
license action or payload has not changed.
must-display
When true, the action's payload must be displayed by clients during
packaging operations. Omission of this value is equivalent to
false. This attribute should not be used for copyright notices.
This attribute should only be used for licenses or other material
that must be displayed during operations. The method of display is
at the discretion of clients. For package updates, this attribute
is ignored if the license action or payload has not changed.
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 so that the tools querying those databases
can operate as if the legacy package were actually installed. In par‐
ticular, 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 dependencies.
The following attributes, named in accordance with the parameters on
pkginfo(5), 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 pro‐
vided.
pkg
The abbreviation for the package being installed. The default value
is the name from the FMRI of the package. This is a legacy action's
key attribute.
vendor
The value for the VENDOR parameter.
version
The value for the VERSION parameter. The default value is the ver‐
sion from the FMRI of the package.
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 that have
specific meaning to the packaging system.
info.classification
One or more tokens that a pkg(7) client can use to classify the
package. The value should have a scheme (such as "org.openso‐
laris.category.2008" or "org.acm.class.1998") and the actual clas‐
sification, 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.fmri
The name and version of the containing package. See "Package FMRIs
and Versions" in the "Description" section.
pkg.human-version
The version scheme used by IPS is strict. See "Package FMRIs and
Versions" in the "Description" section. A more flexible version can
be provided as the value of the pkg.human-version attribute. The
value is displayed by IPS tools such as pkg info, pkg contents, and
pkg search. The pkg.human-version value is not used as a basis for
version comparison and cannot be used in place of the pkg.fmri ver‐
sion.
pkg.obsolete
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.
pkg.renamed
When true, the package has been renamed. There must be one or more
depend actions in the package as well that 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.
pkg.legacy
When true, the package is marked legacy, meaning that it will be
removed in the future.
pkg.summary
A short, one-line description of the package.
Group Actions
The group action defines a UNIX group as defined in group(5). No sup‐
port 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 are recognized:
groupname
The value for the name of the group.
gid
The group's unique numerical id. The default value is the first
free group under 100.
User Actions
The user action defines a local account as defined in /etc/passwd,
/etc/shadow, /etc/group, and /etc/ftpd/ftpusers files. Entries are
added to the appropriate files for users defined with this user action.
The user action is intended to define a user or role account for use by
a system commonent or application. The user action should not be used
for end user or administrator accounts.
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(5).
The special value "UP" can be used to indicate that the passwd(1)
command may be used to set a login password for the user/role
account. When the value of "UP" is listed in the manifest a pkg
verify will not report an unexpected change and pkg fix will not
change the value back to that of the manifest.
Best practice is to deliver role accounts with password="NP" and
deliver a user_attr(5) file that sets roleauth=user.
uid
The unique uid of the user. Default value is first free value under
100.
group
The name of the user's primary group. Must be found in /etc/group.
gcos-field
The value of the gcos field in /etc/passwd. Default value is user‐
name.
home-dir
The user's home directory. This directory must be in the system
image directories and not under another mount point such as /home.
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(5).
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(5).
lastchg
The number of days between January 1, 1970, and the date that the
password was last modified. Default value is empty. See shadow(5).
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(5).
max
The maximum number of days the password is valid. Default value is
empty. See shadow(5).
warn
The number of days before password expires that the user is warned.
See shadow(5).
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(5).
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 17410 specifies
a login expiration of September 1, 2017. See shadow(5).
flag
Set to empty. See shadow(5).
ACTUATORS
In certain contexts, additional operations can be appropriate to exe‐
cute in preparation for or following the introduction of a particular
action. These additional operations are operating system specific and
are generally needed only on a live system image. A live image is the
image mounted at / of the active, running boot environment of the cur‐
rent zone. 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 can result in package installation
failure if the actuator cannot determine a means of making safe instal‐
lation progress.
The following actuators are defined:
reboot-needed
Can be set to true or false. This actuator declares that update or
removal of the tagged action must be performed in a new boot envi‐
ronment if the package system is operating on a live image. Cre‐
ation of a new boot environment is controlled by the be-policy
image property. See the "Image Properties" section in the pkg(1)
man page for more information about the be-policy property.
disable_fmri, refresh_fmri, restart_fmri, suspend_fmri
Each of these actuators takes the value of an FMRI of a service
instance to operate on during the installation or removal of the
package. Fully specify the service instance to avoid ambiguity.
With disable_fmri, refresh_fmri, and restart_fmri, the FMRI value
can contain a pattern that matches multiple service instances. The
pattern to match must be specified explicitly with a glob that is
accepted by the svcs command, rather than implicitly by not indi‐
cating any instances.
If the same service FMRI is tagged by multiple actions, possibly in
multiple packages, the operation specified by that actuator is per‐
formed only once. For example, if multiple restart_fmri actuators
specify the same FMRI, that service is restarted only one time for
that pkg operation.
The following list of SMF actuators describes the effect on the
service FMRI that is the value of each named actuator. In these
descriptions, "uninstalling the package" also includes moving the
file action that delivers the service to a different package.
disable_fmri
Disable (svcadm disable) the specified service prior to unin‐
stalling the package.
refresh_fmri
Refresh (svcadm refresh) the specified service after
installing, updating, or uninstalling the package.
restart_fmri
Restart (svcadm restart) the specified service after
installing, updating, or uninstalling the package.
suspend_fmri
Temporarily disable (svcadm disable -t) the specified service
prior to updating the package, and then enable (svcadm enable)
the service after updating the package. The specified service
value must be a fully specified service instance FMRI (for
example, svc:/site/mysvc:default instead of svc:/site/mysvc)
and cannot include globbing characters. suspend_fmri can be
performed only on services that are enabled and applies only to
package update operations.
SMF actuators are not executed in the following cases:
o When operating on an alternate root (pkg -R
/path/to/BE).
o When recursing from the global zone (pkg subcommand -r).
MEDIATIONS
A mediator is a name that represents a set of related symbolic or hard
links. If two or more link actions have the same path and mediator
name, the user or the package system selects the link target based on
version, implementation, or priority. See "Link Actions" for informa‐
tion about mediator attributes.
The following example shows two different instances of a mediator named
java where the link choices are between versions. These two link
actions would appear in two different packages.
link mediator=java mediator-version=1.6 path=usr/java target=jdk/jdk1.6.0_31
link mediator=java mediator-version=1.7 path=usr/java target=jdk/jdk1.7.0_02
See the set-mediator subcommand in the pkg(1) man page for information
about how to select the version you want for this link path. To have a
choice of versions, both packages must be installed.
CONSTRAINTS AND FREEZING
When a package is transitioned to a new version, or when it is added to
or removed from the system, the version that is chosen, or whether
removal is allowed, is determined by a variety of constraints put on
the package. Those constraints can be defined by other packages in the
form of dependencies, or by the administrator in the form of freezes.
The most common form of constraint is delivered by the require depen‐
dency, as described in "Depend Actions" above. Such a constraint pre‐
vents the package from being downgraded or removed.
Most parts of the operating system are encapsulated by packages called
incorporations. These packages primarily deliver constraints repre‐
sented by the incorporate dependency.
As described above, an incorporated package need not be present on the
system, but if it is, then it specifies both an inclusive minimum ver‐
sion and an exclusive maximum version. For example, if the dependent
FMRI has a version of 1.4.3, then no version less than 1.4.3 would sat‐
isfy the dependency, and neither would any version greater than or
equal to 1.4.4. However, versions that merely extended the dotted
sequence, such as 1.4.3.7, would be allowed.
Incorporations are used to force parts of the system to upgrade syn‐
chronously. For some components, such as the C library and the kernel,
this is a basic requirement. For others, such as a simple userland com‐
ponent on which nothing else has a dependency, the synchronous upgrade
is used merely to provide a known and tested set of package versions
that can be referred to by a particular version of the incorporation.
Since an incorporation is simply a package, it can be removed, and all
the constraints it delivers are therefore relaxed. However, many of the
incorporations delivered by Oracle Solaris are required by the packages
they incorporate because that relaxation would not be safe.
Attempting an upgrade of a package to a version that is not allowed by
an installed incorporation will not attempt to find a newer version of
the incorporation in order to satisfy the request, but will instead
fail. If the constraint itself must be moved, and the incorporation
specifying it cannot be removed, then the incorporation must be
upgraded to a version that specifies a desired version of the con‐
straint. Upgrading an incorporation causes all of the incorporated
packages that would not satisfy the constraints delivered by the new
version to be upgraded as well.
A system administrator can constrain a package by using the pkg freeze
command. The named package is constrained to the version installed on
the system if no version is provided. If a versioned package is pro‐
vided, then this administrative constraint, or freeze, acts as if an
incorporate dependency were installed where the fmri attribute had the
value of the provided package version.
A freeze is never lifted automatically by the packaging system. To
relax a constraint, use the pkg unfreeze command.
PUBLISHERS AND REPOSITORIES
As detailed above, a publisher is simply a name that package clients
use to identify the provider of packages. Publishers can distribute
their packages using package repositories and/or package archives.
There are two types of repositories currently supported by the package
system: origin repositories and mirror repositories.
An origin is a package repository that contains all of the metadata
(such as catalogs, manifests, and search indexes) and content (files)
for one or more packages. If multiple origins are configured for a
given publisher in an image, the package client API attempts to choose
the best origin to retrieve package data from. This is the most common
type of repository, and is implicitly created whenever pkgsend or
pkgrecv is used on a package repository.
A mirror is a package repository that contains only package content
(files). If one or more mirrors are configured for a given publisher in
an image, the client API prefers the mirrors for package content
retrieval and attempts to choose the best one to retrieve package con‐
tent from. If the mirror is unreachable, does not have the required
content, or is slower, the client API retrieves the content from any
configured origin repositories. Mirrors are intended for content shar‐
ing among a trusted set of clients using the dynamic mirror functional‐
ity of pkg.depotd(8). Mirrors are also intended to be used to authenti‐
cate access to package metadata, but distribute the package content
without authentication. For example, a client might be configured with
an https origin that requires an SSL key and certificate pair to
access, and with an http mirror that provides the package content. In
this way, only authorized clients can install or update the packages,
while the overhead of authentication for package content retrieval is
avoided. A mirror can be created by removing all subdirectories of a
repository except those named file and their parents. An origin reposi‐
tory can be also be provisioned as a mirror by using the mirror mode of
pkg.depotd(8).
GLOBAL AND NON-GLOBAL ZONE UPDATE
The pkg system forces non-global zones to be kept in sync with the
global zone. This means that certain packages must be at the same ver‐
sion in the global zone and all non-global zones to ensure the same
kernel is run. To do this, pkg uses parent dependencies to impose cer‐
tain constraints on non-global zones. See "Depend Actions" above for
more information about parent dependencies.
Because of restrictions that the global zone imposes on non-global
zones, the non-global zones must have access to the packages of the
global zone and must have a similar publisher configuration. Both of
these objectives are achieved by using a system repository (see the
pkg.sysrepo(8) man page). The system repository provides access to the
publishers configured in the global zone and information about how
those publishers are configured. To prevent non-global zones from
choosing different packages during installation or update, system pub‐
lishers are ranked higher in the publisher search order than publishers
configured in the non-global zone. See the pkg set-publisher command in
the pkg(1) man page for information about publisher search order.
To update all non-global zones on the system, use the pkg update com‐
mand with no arguments in the global zone. This command operates on the
global zone and on each non-global zone recursively. The minimal
changes necessary are made to non-global zones to bring them in sync
with the changes made in the global zone. For example, suppose package
foo is installed at version 1 in both the global zone and non-global
zones, and suppose version 2 is available in a system repository. If
foo has a parent dependency, then pkg update foo updates foo to version
2 in both the global zone and the non-global zones because the parent
dependency forces the package to stay in sync. If foo does not have a
parent dependency, then foo is updated to version 2 in the global zone
but remains at version 1 in the non-global zones.
FACETS AND VARIANTS
Software can have components that are optional and components that are
mutually exclusive. Examples of optional components include locales and
documentation. Examples of mutually exclusive components include SPARC
or x86 and debug or non-debug binaries.
In IPS, optional components are called facets and mutually exclusive
components are called variants. Facets and variants are specified as
tags on package actions. Each facet and variant tag has a name and a
value. A single action can have multiple facet and variant tags. Exam‐
ples of components with multiple facet and variant tags include an
architecture-specific header file that is used by developers, or a com‐
ponent that is only for a SPARC global zone.
An example of a variant tag is variant.arch=sparc. An example of a
facet tag is facet.devel=true. Facets and variants are often referred
to without the leading facet. and variant..
Facets and variants are special properties of the image and cannot be
set on individual packages. To view the current values of the facets
and variants set on the image, use the pkg facet and pkg variant com‐
mands as shown in the pkg(1) man page. To modify the values of the
facets and variants set on the image, use the pkg change-facet and pkg
change-variant commands.
Facets are treated as boolean values by package clients: Facets can be
set only to true (enabled) or false (disabled) in the image. By
default, all facets starting with 'facet.debug.' or 'facet.optional.'
are considered to be set to false in the image; all others are consid‐
ered to be set to true in the image.
Facets can be either set locally within an image using the pkg change-
facet command or inherited from a parent image. For example, a non-
global zone can inherit a facet from the global zone. Inherited facets
are evaluated before, and take priority over, any locally set facets.
If the same facet is both inherited and locally set, the inherited
facet value masks the locally set value. Masked facets have no effect
on facet evaluation and package actions. Facet changes made by using
the pkg change-facet command only affect locally set facets. Inherited
facets can only be changed by making the change in the parent image. By
default, the pkg facet command does not display masked facets.
The value of a facet tag on an action can be set to all or true to con‐
trol how clients filter faceted actions. All values other than all or
true have undefined behavior. See below for a description of the condi‐
tions that must exist in the image to install an action that has facet
tags.
The all value for a facet is useful when more than a single level of
filtering is required. In the following example, foo.txt is installed
only if the doc facet and at least one of the locale facets is true in
the image. This enables administrators to exclude documentation, but
still enable or disable support for specific locales. In addition,
api.txt is only installed if both the doc and devel facets are true in
the image.
file path=usr/share/doc/foo/foo.txt facet.doc=all facet.locale.en_GB=true facet.locale.en_US=true
file path=usr/share/doc/foo/api.txt facet.doc=all facet.devel=all
A facet set on the image can be a full facet such as doc.man or a pat‐
tern such as locale.*. This is useful when you want to disable a por‐
tion of the facet namespace, and only enable individual facets within
it. For example, you could disable all locales and then only enable one
or two specific locales, as shown in the following example:
# pkg change-facet locale.*=false
[output about packages being updated]
# pkg change-facet locale.en_US=true
[output about packages being updated]
Most variants can have any number of values. For example, the arch
variant can be set to i386, sparc, ppc, arm, or whatever architectures
the distribution supports. (Only i386 and sparc are used in Oracle
Solaris.) The exception are the debug variants. The debug variants
should only be set to true or false; other values have undefined behav‐
ior. If a file action has both non-debug and debug versions, both ver‐
sions must have the applicable debug variant explicitly set, as shown
in the following example:
file group=sys mode=0644 overlay=allow owner=root \
path=etc/motd pkg.csize=115 pkg.size=103 preserve=true \
variant.debug.osnet=true
file group=sys mode=0644 overlay=allow owner=root \
path=etc/motd pkg.csize=68 pkg.size=48 preserve=true \
variant.debug.osnet=false
The variant value must be set on the image in order for a package using
the variant to be installed; by default all unspecified variants have
the value 'false', which may or may not make the package installable.
The arch and zone variants are set by the program that creates the
image and installs its initial contents.
The facets and variants set on the image affect whether a particular
action is installed.
o Actions with no facet or variant tags are always installed.
o Actions with facet tags are installed if the following con‐
ditions exist in the image:
o All facet tags on the action that have a value of all
are true in the image (false is the default for all
facets starting with 'facet.debug.' or
'facet.optional.'; true is the default for all others).
o If any facet tags on the action have a value of true, at
least one of those facets is true in the image.
o Actions with variant tags are installed only if the values
of all the variant tags are the same as the values set in
the image.
o Actions with both facet and variant tags are installed if
both the facets and the variants allow the action to be
installed.
You can create custom facet tags and variant tags. See Packaging and
Delivering Software With the Image Packaging System in Oracle Solaris
11.4 for more information. The following tags are in common use in Ora‐
cle Solaris.
tab(); lw(2.75i) lw(2.75i) lw(2.75i) lw(2.75i) Variant NamePossible
Values _ variant.archsparc, i386 variant.opensolaris.zoneglobal, non‐
global variant.debug.*true, false
The following list shows a small sample of the facet tags that are used
in Oracle Solaris:
facet.devel facet.doc
facet.doc.html facet.doc.info
facet.doc.man facet.doc.pdf
facet.locale.de facet.locale.en_GB
facet.locale.en_US facet.locale.fr
facet.locale.ja_JP facet.locale.zh_CN
IMAGE POLICIES
Image policies are defined by image properties with boolean values. See
"Image Properties" in the pkg(1) man page for descriptions of the
flush-content-cache-on-success and send-uuid properties and information
about how to view and modify their values.
FILES
Since pkg(7) images can be located arbitrarily within a larger file
system, the token $IMAGE_ROOT is used 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 the metadata of a particular image, certain files and directo‐
ries can contain information useful during repair and recovery. The
token $IMAGE_META is used to refer to the top-level directory that con‐
tains 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 pack‐
age operation.
$IMAGE_META/publisher
Contains a directory for each publisher. Each directory stores pub‐
lisher-specific metadata.
Other paths within the $IMAGE_META directory hierarchy are Private, and
are subject to change.
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) ATTRIBUTE TYPEAT‐
TRIBUTE VALUE _ Availabilitypackage/pkg _ Interface StabilityUncommit‐
ted
SEE ALSO
pkg(1), pkgdepend(1), pkgdiff(1), pkgfmt(1), pkglint(1), pkgmerge(1),
pkgmogrify(1), pkgrecv(1), pkgrepo(1), pkgsend(1), pkgsign(1), pkg‐
surf(1), pkg.depotd(8), pkg.sysrepo(8), svcs(1), svcadm(8)
Updating Systems and Adding Software in Oracle Solaris 11.4
Creating Package Repositories in Oracle Solaris 11.4
Packaging and Delivering Software With the Image Packaging System in
Oracle Solaris 11.4
https://github.com/oracle/solaris-ips
Oracle Solaris 11.4 3 Apr 2020 pkg(7)