pkg.7

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE refentry PUBLIC "-//Sun Microsystems//DTD SolBook-XML 3.7//EN" "xsolbook.dtd" [
<!ENTITY % ent SYSTEM "entities.ent">
%ent;
]>

<refentry id="pkg-7">
<refmeta><refentrytitle>pkg</refentrytitle><manvolnum>7</manvolnum>
<refmiscinfo class="date">28 Jan 2025</refmiscinfo>
<refmiscinfo class="sectdesc">&man7;</refmiscinfo>
<refmiscinfo class="software">&release;</refmiscinfo>
<refmiscinfo class="arch">generic</refmiscinfo>
<refmiscinfo class="copyright">Copyright (c) 2009, 2025, Oracle and/or its affiliates.</refmiscinfo>
</refmeta>
<refnamediv>
<refname>pkg</refname><refpurpose>Image Packaging System</refpurpose>
</refnamediv>
<refsect1 id="GLHDA" role="description"><title></title>
<para>The Image Packaging System, <literal>pkg</literal>(7), is a framework
that 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 file system, but
they also represent other installable objects, such as drivers, services,
and users.</para>
</refsect1>
<refsect1 role="other"><title>Package FMRIs and Versions</title>
<para>Each package is represented by a fault management resource identifier
(FMRI) with the scheme <literal>pkg:</literal>. The full FMRI for a package
consists of the scheme, a publisher, the package name, and a version string in
the following format:</para>
<screen>pkg://solaris/system/library/c++-runtime@11.4-11.4.0.0.1.1.2:20170919T184404Z</screen>
<para><literal>solaris</literal> is the publisher.
<literal>system/library/c++-runtime</literal> 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 <literal>pkg://</literal> if present. An FMRI that includes
the publisher is often referred to as being &ldquo;fully qualified.&rdquo; If
publisher information is not present, then the package name should generally be
preceded by <literal>pkg:/</literal>.</para>
<para>Packaging clients often allow the scheme of an FMRI to be omitted if it
does not contain publisher information. For example,
<literal>pkg:/system/library/c++-runtime</literal> can be written as
<literal>system/library/c++-runtime</literal>. If the scheme is omitted,
clients also allow omission of all but the last component of a package name for
matching purposes. For example, <literal>system/library/c++-runtime</literal>
could be written as <literal>library/c++-runtime</literal> or
<literal>c++-runtime</literal>, which would then match packages named
<literal>c++-runtime</literal> or package names ending in
<literal>/c++-runtime</literal>.</para>
<para>A publisher name identifies a person, group of persons, or an
organization 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.</para>
<para>The version follows the package name, separated by an at (@) sign. The
version consists of a component version, a branch version, and a timestamp. 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.</para>
<para><emphasis role="strong">Component version: 11.4.</emphasis> For components
tightly bound to the operating system, the component version number is
<replaceable>minor.update</replaceable>. 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 arbitrarily long.</para>
<para><emphasis role="strong">Branch version: 11.4.0.0.1.1.2.</emphasis> The
branch version, if present, must follow a hyphen (-). The branch version string
is the same as the &ldquo;Branch&rdquo; in <command>pkg info</command> output.</para>
<para>Oracle Solaris packages show the following information in the branch
version portion of the version string of a package FMRI:</para>
<programlisting><replaceable>minor.update.sru.order.platform.build.rev</replaceable></programlisting>
<variablelist termlength="wholeline">
<varlistentry><term><emphasis role="strong">Minor release number: 11</emphasis></term>
<listitem><para>The <replaceable>minor</replaceable> portion of
<replaceable>major.minor</replaceable> that is output by the
<command>uname -r</command>.</para></listitem></varlistentry>
<varlistentry><term><emphasis role="strong">Update release number: 4</emphasis></term>
<listitem><para>The update release number for this Oracle Solaris release.</para></listitem></varlistentry>
<varlistentry><term><emphasis role="strong">SRU number: 0</emphasis></term>
<listitem><para>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.</para></listitem></varlistentry>
<varlistentry><term><emphasis role="strong">Order: 0</emphasis></term>
<listitem><para>This value is used internally.</para></listitem></varlistentry>
<varlistentry><term><emphasis role="strong">Platform: 1</emphasis></term>
<listitem><para>This value is used internally.</para></listitem></varlistentry>
<varlistentry><term><emphasis role="strong">Release or SRU build number: 1</emphasis></term>
<listitem><para>The build number of the SRU, or the respin number for the release.</para></listitem></varlistentry>
<varlistentry><term><emphasis role="strong">Revision or nightly build number: 2</emphasis></term>
<listitem><para>The build number for the individual nightly builds.</para></listitem></varlistentry>
</variablelist>
<para>If the package is an Interim Diagnostic or Relief (IDR) update, then the
branch version of the package FMRI contains the following two additional 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
<literal>pkg://solaris/idr824@4,5.11:20131114T034951Z</literal> and contains
packages such as
<literal>pkg://solaris/system/library@11.4-11.4.0.0.1.1.2.824.4</literal>:</para>
<variablelist termlength="wholeline">
<varlistentry><term><emphasis role="strong">IDR: 824</emphasis></term>
<listitem><para>The name of the IDR.</para></listitem></varlistentry>
<varlistentry><term><emphasis role="strong">IDR ID: 4</emphasis></term>
<listitem><para>The version of the IDR.</para></listitem></varlistentry>
</variablelist>
<para><emphasis role="strong">Timestamp: 20170919T184404Z.</emphasis> The timestamp must follow a colon (:). The timestamp is the time the package was published in ISO-8601 basic format: <replaceable>YYYYMMDDTHHMMSSZ</replaceable>.</para>
<para>When performing comparisons between versions, no component of the full
version is considered unless the components to its left are the same. Thus,
<literal>4.3-1</literal> is greater than <literal>4.2-7</literal> because
<literal>4.3</literal> is greater than <literal>4.2</literal>, and
<literal>4.3-3</literal> is greater than <literal>4.3-1</literal> because
<literal>3</literal> is greater than <literal>1</literal>.</para>
<para>The <literal>pkg.human-version</literal> attribute can be used to provide
a human-readable version string. The value of the
<literal>pkg.human-version</literal> 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 &ldquo;Set Actions&rdquo; for more information.</para>
<para>Many parts of the system, when appropriate, abridge FMRIs when displaying
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 versioning information can be
omitted.</para>
</refsect1>
<refsect1 role="other"><title>Actions</title>
<para>Actions represent the installable objects on a system. Actions are described in the manifest of a package.</para>
<para>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 <command>pkg update</command> command. For more information, see <olink targetdoc="PKDEV"><citetitle remap="book">Packaging and Delivering Software With the Image Packaging System in Oracle Solaris 11.4</citetitle></olink>.</para>
<para>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 can have other attributes. Some attributes are interpreted directly by the packaging system. Other attributes might be useful only to the system administrator or the end-user.</para>
<para>Actions have a simple text representation:</para>
<programlisting><replaceable>action_name</replaceable> <replaceable>attribute1</replaceable>=<replaceable>value1</replaceable> <replaceable>attribute2</replaceable>=<replaceable>value2</replaceable> ...</programlisting>
<para>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 (&bsol;)
character to avoid terminating the quoted string. A backslash can be escaped
with a backslash.</para>
<para>Actions can have multiple attributes. Some attributes can be named multiple
times with different values for a single action. Multiple attributes with
the same name are treated as unordered lists.</para>
<para>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 combination can be split.</para>
<para>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.</para>
<para>Some attributes cause additional operations to be executed outside of
the packaging context. These attributes are documented in the &ldquo;Actuators&rdquo;
section below.</para>
<para>Actions that are installed to a path must not deliver content to any of
the following paths:</para>
<programlisting>/system/volatile
/tmp
/var/share
/var/tmp</programlisting>
<para>Additionally, the following directories are reserved for use by the system
and should also not be used by actions:</para>
<programlisting>/var/pkg</programlisting>
<refsect2><title>File Actions</title>
<para>The <literal>file</literal> action represents an ordinary file. The <literal>
file</literal> action references a payload, and has four standard attributes:</para>
<variablelist>
<varlistentry><term><literal>path</literal></term>
<listitem><para>The file system path where the file is installed. This is
a <literal>file</literal> action's key attribute.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>mode</literal></term>
<listitem><para>The access permissions (in numeric form) of the file. These
are simple permissions only, not ACLs.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>owner</literal></term>
<listitem><para>The name of the user that owns the file.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>group</literal></term>
<listitem><para>The name of the group that owns the file.</para>
</listitem>
</varlistentry>
</variablelist>
<para>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 <literal>
SHA-1</literal> 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 <olink targetdoc="refman" targetptr="pkgsend-1"><citerefentry><refentrytitle>pkgsend</refentrytitle><manvolnum>1</manvolnum></citerefentry></olink>. 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.</para>
<para>The <literal>preserve</literal> and <literal>overlay</literal> attributes
affect whether and how a <literal>file</literal> action is installed.</para>
<variablelist termlength="wholeline">
<varlistentry><term><literal>preserve</literal></term>
<listitem><para>Specifies when and how files are preserved during package
operations.</para>
<para>When a package is initially installed, if a file delivered by the package
has a <literal>preserve</literal> attribute defined with any value except
<literal>abandon</literal> or <literal>install-only</literal> and the file
already exists in the image, the existing file is stored in
<filename>/var/pkg/lost+found</filename> and the packaged file is
installed.</para>
<para>When a package is initially installed, if a file
delivered by the package has a <literal>preserve</literal> attribute
defined and the file does not already exist in the image, whether that file
is installed depends on the value of the <literal>preserve</literal>
attribute:</para>
<itemizedlist>
<listitem><para>If the value of <literal>preserve</literal> is
<literal>abandon</literal> or <literal>legacy</literal>, the packaged file
is not installed.</para></listitem>
<listitem><para>If the value of <literal>preserve</literal> is not
<literal>abandon</literal> or <literal>legacy</literal>, the packaged file
is installed.</para></listitem>
</itemizedlist>
<para>When a package is downgraded, if a file delivered by the downgraded
version of the package has a <literal>preserve</literal> attribute defined
with any value except <literal>abandon</literal> or
<literal>install-only</literal> and all of the following conditions are
true, the file that currently exists in the image is renamed with the
extension <filename>.update</filename>, and the file from the downgraded
package is installed.</para>
<itemizedlist>
<listitem><para>The file exists in the image.</para></listitem>
<listitem><para>The content of the file delivered by the downgraded version
of the package is different from the content of the file delivered by the
currently installed version of the package.</para></listitem>
<listitem><para>The content of the file delivered by the downgraded version
of the package is different from the content of the file that exists in the
image.</para></listitem>
</itemizedlist>
<para>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.</para>
<para>When a package is upgraded, if a <literal>file</literal> action delivered
by the upgraded version of the package has a <literal>preserve</literal> attribute
defined with any value and the <literal>file</literal> action is the same
as the <literal>file</literal> 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.</para>
<para>When a package is upgraded, if a <literal>file</literal> action delivered
by the upgraded version of the package has a <literal>preserve</literal> attribute
defined and the <literal>file</literal> action is new or is different from
the <literal>file</literal> action delivered by the currently installed version
of the package, the upgrade is done in the following way:</para>
<itemizedlist>
<listitem><para>If the file delivered by the upgraded version of the package has
a <literal>preserve</literal> value of <literal>abandon</literal> or
<literal>install-only</literal> in the upgraded package, the new file will
not be installed and the existing file will not be modified.
</para></listitem>
<listitem><para>If the file delivered by the package has a
<literal>preserve</literal> value of <literal>abandon</literal> then any
attempt to revert the file will not restore the file. Any
<literal>revert-tag</literal> associated with the file will be ignored.
</para></listitem>
<listitem><para>If the file does not exist in the image, the new file is installed.
</para></listitem>
<listitem><para>If the file delivered by the upgraded version of the package
exists in the image, did not exist in the currently installed version of the
package, and was not renamed or moved by using the <literal>original_name</literal> attribute
(see below), then the existing file is stored in <filename>/var/pkg/lost+found</filename> and
the file delivered by the upgraded version of the package is installed.</para>
</listitem>
<listitem><para>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 version of the package, the upgrade is done according
to the value of the <literal>preserve</literal> attribute:</para>
<itemizedlist>
<listitem><para>If the file delivered by the upgraded version of the package
has a <literal>preserve</literal> value of <literal>renameold</literal>, the
existing file is renamed with the extension <filename>.old</filename>, and
the new file is installed with updated permissions and timestamp (if present).
See the <literal>timestamp</literal> attribute description below.</para>
</listitem>
<listitem><para>If the file delivered by the upgraded version of the package
has a <literal>preserve</literal> value of <literal>renamenew</literal>, the
new file is installed with the extension <filename>.new</filename> and the
existing file is not modified.</para></listitem>
<listitem><para>If the file delivered by the upgraded version of the package
has a <literal>preserve</literal> value of <literal>true</literal>, the new
file is not installed, but the permissions and timestamp (if present) are
reset on the existing file.</para></listitem>
</itemizedlist>
</listitem>
<listitem><para>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 <literal>preserve</literal> value
of either <literal>renameold</literal> or <literal>renamenew</literal>, the
existing file is replaced by the file delivered by the upgraded version of
the package, including replacing permissions and timestamp (if present).</para>
</listitem>
<listitem><para>If the file delivered by the upgraded version of the package
exists in the image, has a <literal>preserve</literal> value of <literal>legacy</literal> in
the upgraded package, and has a different <literal>preserve</literal> value
in the currently installed version of the package, the existing file is renamed
with the extension <literal>.legacy</literal>, and the new file is installed
with updated permissions and timestamp (if present).</para></listitem>
<listitem><para>If the file delivered by the upgraded version of the package
exists in the image and has a <literal>preserve</literal> value of <literal>legacy
</literal> 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.</para></listitem>
</itemizedlist>
<para>Unless otherwise specified above, when a package is downgraded or
upgraded, any <literal>file</literal> 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 <literal>file</literal>
action delivered by the package is removed.</para>
<para>When a package is uninstalled, if a <literal>file</literal> action
delivered by the currently installed version of the package has a
<literal>preserve</literal> value of <literal>abandon</literal> and the file
exists in the image, the file is not removed. However, any other
<literal>file</literal> action delivered by that package that is removed, that
has a <literal>preserve</literal> attribute specified, and that has been
modified since it was originally installed is moved to
<filename>/var/pkg/lost+found</filename>.</para></listitem>
</varlistentry>
<varlistentry><term><literal>overlay</literal></term>
<listitem><para>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, <filename>/etc/motd</filename>)
and that can be safely overwritten.</para>
<para>If <literal>overlay</literal> is not specified, multiple packages cannot
deliver files to the same location.</para>
<para>The <literal>overlay</literal> attribute can have one of the following
values:</para>
<variablelist>
<varlistentry><term><literal>allow</literal></term>
<listitem><para>One other package is allowed to deliver a file to the same
location. This value has no effect unless the <literal>preserve</literal> attribute
is also set.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>true</literal></term>
<listitem><para>The file delivered by the action overwrites any other action
that has specified <literal>allow</literal>.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Changes to the installed file are preserved based on the value of the <literal>
preserve</literal> 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 <literal>preserve</literal> attribute was specified.
Only one action can overlay another, and the <literal>mode</literal>, <literal>owner
</literal>, and <literal>group</literal> attributes must match.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>overlay-attributes</literal></term>
<listitem><para>Specifies whether image-modifying operations such as install,
update, etc. should report errors when an overlaying action has a different
<literal>owner</literal>, <literal>group</literal>, <literal>mode</literal>
or <literal>sysattr</literal> from its overlaid action.
<literal>overlay-attributes</literal> is usually used in actions with
<literal>overlay</literal> equal to <literal>allow</literal> or
<literal>deny</literal>. When the value of
<literal>overlay-attributes</literal> for either overlaying action or overlaid
action is <literal>deny</literal>, an error will be generated during image-modifying
operations. Also verification operations will generate an error on those mismatched attributes:
<literal>owner</literal>, <literal>group</literal> and <literal>mode</literal>
if <literal>overlay</literal> is equal to <literal>deny</literal> 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
<literal>overlay-attributes</literal>, mismatched attributes
when comparing the on-disk attributes of a file to its packaged
version will always be reported as errors.
</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>dehydrate</literal></term>
<listitem><para>Specifies whether this action should be removed when a package publisher's packages are dehydrated or when a dehydrated publisher's packages are modified. The value of the <literal>dehydrate</literal> attribute can be <literal>true</literal> or <literal>false</literal>. If the value of the <literal>dehydrate</literal> attribute is <literal>false</literal>, the action will not be removed during dehydrate operations. Otherwise, the action will be removed. File actions tagged with the <literal>preserve</literal> or <literal>overlay</literal> attributes are implicitly excluded from dehydration operations and do not need this attribute.
</para>
<programlisting>file path=etc/zones/SYSdefault.xml dehydrate=false ...</programlisting>
</listitem>
</varlistentry>
</variablelist>
<para>The following attributes are recognized for ELF files:</para>
<variablelist termlength="wholeline">
<varlistentry><term><literal>elfarch</literal></term>
<listitem><para>The architecture of the ELF file. This is the output of <command>
uname -p</command> on the architecture for which the file is built.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>elfbits</literal></term>
<listitem><para>This is <literal>32</literal> or <literal>64</literal>.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>elfhash</literal></term>
<listitem><para>This is the hash of the &ldquo;interesting&rdquo; 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.</para>
</listitem>
</varlistentry>
</variablelist>
<para>The following additional attributes are recognized for <literal>file</literal> actions:</para>
<variablelist termlength="wholeline">
<varlistentry><term><literal>original_name</literal></term>
<listitem><para>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 <literal>original_name</literal> attribute
if specified. Any editable file being installed that has the <literal>original_name
</literal> attribute set uses the file of that name if it is deleted as part
of the same packaging operation.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>release-note</literal></term>
<listitem><para>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 special FMRI of <literal>feature/pkg/self
</literal> refers to the containing package. If the version of <literal>feature/pkg/self
</literal> is 0, this file will only be part of the release notes on initial
installation.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>revert-tag</literal></term>
<listitem><para>This attribute is used to tag editable files that should be
reverted as a set. The value of the <literal>revert-tag</literal> attribute
is a <replaceable>tagname</replaceable>. Multiple <literal>revert-tag</literal> attributes
can be specified for a single <literal>file</literal> action. The file reverts
to its manifest-defined state when <command>pkg revert</command> is invoked
with any of those tags specified. See the <olink targetdoc="refman" targetptr="pkg-1"><citerefentry><refentrytitle>pkg</refentrytitle><manvolnum>1</manvolnum></citerefentry></olink> man page
for information about the <command>pkg revert</command> command.</para>
<para>The <literal>revert-tag</literal> attribute can also be specified at the directory level. See &ldquo;Directory Actions&rdquo; below.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>sysattr</literal></term>
<listitem><para>This attribute is used to specify any system attributes that should be set for this file. The value of the <literal>sysattr</literal> attribute can be a comma-separated list of verbose system attributes or a string sequence of compact system attribute options, as shown in the following examples. Supported system attributes are explained in the <olink targetdoc="refman" targetptr="chmod-1"><citerefentry><refentrytitle>chmod</refentrytitle><manvolnum>1</manvolnum></citerefentry></olink> 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.</para>
<programlisting>file path=opt/secret_file sysattr=hidden,sensitive
file path=opt/secret_file sysattr=HT</programlisting>
</listitem>
</varlistentry>
<varlistentry><term><literal>timestamp</literal></term>
<listitem><para>This attribute is used to set the access and modification
time on the file. The <literal>timestamp</literal> attribute value must be
expressed in UTC in ISO-8601 format, omitting the colons and hyphens.</para>
<para>The <literal>timestamp</literal> attribute is essential when packaging <filename>.pyc</filename> or <filename>.pyo</filename> files for Python. The related <filename>.py</filename> file for the <filename>.pyc</filename> or <filename>.pyo</filename> files must be marked with the timestamp embedded within those files, as shown in the following example:</para>
<programlisting>file path=usr/lib/python2.7/vendor-packages/pkg/__init__.pyc ...
file path=usr/lib/python2.7/vendor-packages/pkg/__init__.py &bsol;
     timestamp=20130311T221521Z ...</programlisting>
</listitem>
</varlistentry>
</variablelist>
<para>The following attributes for <literal>file</literal> actions are automatically generated by the system and should not be specified by package developers:</para>
<variablelist termlength="wholeline">
<varlistentry><term><literal>hash</literal></term>
<listitem><para>The SHA-1 hash of the uncompressed file.</para></listitem>
</varlistentry>
<varlistentry><term><literal>chash</literal></term>
<listitem><para>The SHA-1 hash of the compressed file.</para></listitem>
</varlistentry>
<varlistentry><term><literal>pkg.size</literal></term>
<listitem><para>The size in bytes of the uncompressed file.</para></listitem>
</varlistentry>
<varlistentry><term><literal>pkg.csize</literal></term>
<listitem><para>The size in bytes of the compressed file.</para></listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2><title>Directory Actions</title>
<para>The <literal>dir</literal> action is like the <command>file</command> action in that it
represents a file system object. The <literal>dir</literal> action represents a directory instead of
an ordinary file. The <literal>dir</literal> action has the same <literal>path</literal>,
<literal>mode</literal>, <literal>owner</literal>, and <literal>group</literal> attributes that the
<literal>file</literal> action has, and <literal>path</literal> is the key attribute. The <literal>dir</literal> action also accepts the <literal>revert-tag</literal> attribute. The value of the <literal>revert-tag</literal> attribute is different for <literal>file</literal> and <literal>dir</literal> actions.</para>
<para>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
<filename>$IMAGE_META/lost+found</filename>. See the &ldquo;Files&rdquo; section for more
information about <literal>$IMAGE_META</literal>.</para>
<variablelist termlength="wholeline">
<varlistentry>
<term><literal>revert-tag</literal></term>
<listitem>
<para>This attribute is used to identify unpackaged files that should be removed as a set. See
&ldquo;File Actions&rdquo; above for a description of how to specify this attribute for
<literal>file</literal> actions. For directories, the value of the <literal>revert-tag</literal>
attribute is
<replaceable>tagname</replaceable><literal>=</literal><replaceable>pattern</replaceable>. Multiple
<literal>revert-tag</literal> attributes can be specified for a single <literal>dir</literal>
action. When <command>pkg revert</command> is invoked with a matching
<replaceable>tagname</replaceable>, any unpackaged files or directories under this
<literal>dir</literal> directory that match <replaceable>pattern</replaceable> (using shell globbing
characters) are removed. See the <olink targetdoc="refman" targetptr="pkg-1"><citerefentry><refentrytitle>pkg</refentrytitle><manvolnum>1</manvolnum></citerefentry></olink> man page for information about the
<command>pkg revert</command> command.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>salvage-from</literal></term>
<listitem><para>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
<literal>salvage-from</literal> attribute inherits on creation any contents of the directory named
in the value of the <literal>salvage-from</literal> attribute.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2><title>Link Actions</title>
<para>The <literal>link</literal> action represents a symbolic link. The <literal>link</literal>
action has the following standard attributes:</para>
<variablelist termlength="wholeline">
<varlistentry><term><literal>path</literal></term>
<listitem><para>The file system path where the symbolic link is installed.
This is a <literal>link</literal> action's key attribute.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>target</literal></term>
<listitem><para>The target of the symbolic link. The file system object to
which the link resolves.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>mediator</literal></term>
<listitem><para>Specifies the entry in the mediation namespace shared by all
path names participating in a given mediation group (for example, <literal>python
</literal>). Link mediation can be performed based on <literal>mediator-version</literal> and/or <literal>
mediator-implementation</literal>. All mediated links for a given path name
must specify the same mediator. However, not all mediator versions 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 <literal>mediator
</literal>, in combination with a specific version and/or implementation represents
a mediation that can be selected for use by the packaging system.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>mediator-version</literal></term>
<listitem><para>Specifies the version (expressed as a dot-separated sequence
of nonnegative integers) of the interface described by the <literal>mediator</literal> attribute.
This attribute is required if <literal>mediator</literal> is specified and <literal>
mediator-implementation</literal> is not. A local system administrator can
set the version to use explicitly. The value specified should generally match
the version of the package delivering the link (for example, <literal>runtime/python-27
</literal> should use <literal>mediator-version=2.7</literal>), although this
is not required.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>mediator-implementation</literal></term>
<listitem><para>Specifies the implementation of the mediator for use in addition
to or instead of the <literal>mediator-version</literal>. Implementation strings
are not considered to be ordered and a string is arbitrary selected by <literal>pkg
</literal>(7) if not explicitly specified by a system administrator.</para>
<para>The value can be a string of arbitrary length composed of alphanumeric
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.</para>
<para>If only one instance of an implementation mediation link at a particular
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.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>mediator-priority</literal></term>
<listitem><para>When resolving conflicts in mediated links, <literal>pkg</literal>(7)
normally chooses the link with the greatest value of <literal>mediator-version</literal> or
based on <literal>mediator-implementation</literal> if that is not possible.
This attribute is used to specify an override for the normal conflict resolution
process.</para>
<para>If this attribute is not specified, the default mediator selection logic
is applied.</para>
<para>If the value is <literal>vendor</literal>, the link is preferred over
those that do not have a <literal>mediator-priority</literal> specified.</para>
<para>If the value is <literal>site</literal>, the link is preferred over
those that have a value of <literal>vendor</literal> or that do not have a <literal>
mediator-priority</literal> specified.</para>
<para>A local system administrator can override the selection logic described
above.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2><title>Hardlink Actions</title>
<para>The <literal>hardlink</literal> action represents a hard link. It has
the same attributes as the <literal>link</literal> action, and <literal>path</literal> is
also its key attribute.</para>
</refsect2>
<refsect2><title>Driver Actions</title>
<para>The <literal>driver</literal> action represents a device driver. The <literal>
driver</literal> action does not reference a payload. The driver files themselves
must be installed as <literal>file</literal> actions. The following attributes
are recognized (see <olink targetdoc="refman" targetptr="add-drv-8"><citerefentry><refentrytitle>add_drv</refentrytitle><manvolnum>8</manvolnum></citerefentry></olink> for more information):</para>
<variablelist termlength="wholeline">
<varlistentry><term><literal>name</literal></term>
<listitem><para>The name of the driver. This is usually, but not always, the
file name of the driver binary. This is the <literal>driver</literal> action's
key attribute.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>alias</literal></term>
<listitem><para>This represents an alias for the driver. A given driver can
have more than one <literal>alias</literal> attribute. No special quoting
rules are necessary.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>class</literal></term>
<listitem><para>This represents a driver class. A given driver can have more
than one <literal>class</literal> attribute.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>perms</literal></term>
<listitem><para>This represents the file system permissions for the driver's
device nodes.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>clone_perms</literal></term>
<listitem><para>This represents the file system permissions for the clone
driver's minor nodes for this driver.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>policy</literal></term>
<listitem><para>This specifies additional security policy for the device.
A given driver can have more than one <literal>policy</literal> attribute,
but no minor device specification can be present in more than one attribute.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>privs</literal></term>
<listitem><para>This specifies privileges used by the driver. A given driver
can have more than one <literal>privs</literal> attribute.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>devlink</literal></term>
<listitem><para>This specifies an entry in <filename>/etc/devlink.tab</filename>. The value is the exact line to go into the file, with tabs denoted by <literal>&bsol;t</literal>. See <olink targetdoc="refman" targetptr="devlinks-8"><citerefentry><refentrytitle>devlinks</refentrytitle><manvolnum>8</manvolnum></citerefentry></olink> for more information. A given driver can have more than one <literal>devlink</literal> attribute.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2><title>Depend Actions</title>
<para>The <command>depend</command> 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.</para>
<para>The following attributes are recognized:</para>
<variablelist termlength="wholeline">
<varlistentry><term><literal>fmri</literal></term>
<listitem><para>The FMRI representing the dependent package. This is the <literal>
dependency</literal> action's key attribute. The <literal>fmri</literal> value
must not include the publisher. The package name is assumed to be complete.
Dependencies of type <literal>group-any</literal> and <literal>require-any</literal>
can have multiple <literal>fmri</literal> attributes. A version is optional on
the <literal>fmri</literal> value, though for some types of dependencies, an
<literal>fmri</literal> with no version has no meaning or the version is
ignored.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>type</literal></term>
<listitem><para>The type of the dependency.</para>
<variablelist termlength="wholeline">
<varlistentry><term><literal>require</literal></term>
<listitem><para>The dependency is required and must have a version equal to
or greater than the version specified in the <literal>fmri</literal> 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.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>optional</literal></term>
<listitem><para>The dependency, if present, must be at the specified version
level or greater.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>exclude</literal></term>
<listitem><para>The containing package cannot be installed if the dependency
is present at the specified version level or greater. If no version is specified,
the dependent package cannot be installed concurrently with the package specifying
the dependency.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>incorporate</literal></term>
<listitem><para>The dependency is optional, but the version of the dependent
package is constrained. See &ldquo;Constraints and Freezing&rdquo; below.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>require-any</literal></term>
<listitem><para>Any one of the packages specified by multiple <literal>fmri</literal>
attributes can satisfy the dependency, following the same rules as the <literal>require</literal>
dependency type.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>conditional</literal></term>
<listitem><para>The dependency is required only if the package defined by
the <literal>predicate</literal> attribute is present on the system.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>origin</literal></term>
<listitem><para>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 <literal>root-image</literal> attribute is
<literal>true</literal>, this applies to the image mounted at / instead.</para>
<para>If the value of the <literal>root-image</literal> attribute is
<literal>true</literal> and the value of the <literal>fmri</literal> attribute
starts with <literal>pkg:/feature/firmware/</literal>, the remainder of the
<literal>fmri</literal> value is treated as a command in
<filename>/usr/lib/fwenum</filename> that evaluates the firmware dependency. See
<olink targetdoc="PKDEV"><citetitle remap="book">Packaging and Delivering Software With the Image Packaging System in Oracle Solaris 11.4</citetitle></olink> for examples.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>group</literal></term>
<listitem><para>The dependency is required unless the package is on the image
avoid list. Note that obsolete packages silently satisfy the group dependency.
See the <command>avoid</command> subcommand in <olink targetdoc="refman" targetptr="pkg-1"><citerefentry><refentrytitle>pkg</refentrytitle><manvolnum>1</manvolnum></citerefentry></olink>.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>group-any</literal></term>
<listitem><para>Any one of multiple dependent packages as specified by multiple
<literal>fmri</literal> attributes can satisfy the dependency, following the
same rules as the <literal>group</literal> dependency type with the exception
that non-obsolete package stems are preferred over obsolete ones.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>parent</literal></term>
<listitem><para>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 <literal>parent</literal> dependency
is the same as that used for <literal>incorporate</literal> dependencies.</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry><term><literal>predicate</literal></term>
<listitem><para>The FMRI representing the predicate for <literal>conditional</literal> dependencies.
</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>root-image</literal></term>
<listitem><para>Has an effect only for <literal>origin</literal> dependencies
as mentioned above.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2><title>License Actions</title>
<para>The <literal>license</literal> 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 <literal>license</literal> action.</para>
<para>The payload of the <literal>license</literal> 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, <literal>license</literal> 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.</para>
<para>The following attributes are recognized:</para>
<variablelist termlength="wholeline">
<varlistentry><term><literal>license</literal></term>
<listitem><para>This is a <literal>license</literal> action's key attribute.
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:</para>
<itemizedlist>
<listitem><para>ABC Co. Copyright Notice</para></listitem>
<listitem><para>ABC Co. Custom License</para></listitem>
<listitem><para>Common Development and Distribution License 1.0 (CDDL)</para>
</listitem>
<listitem><para>GNU General Public License 2.0 (GPL)</para></listitem>
<listitem><para>GNU General Public License 2.0 (GPL) Only</para></listitem>
<listitem><para>MIT License</para></listitem>
<listitem><para>Mozilla Public License 1.1 (MPL)</para></listitem>
<listitem><para>Simplified BSD License</para></listitem>
</itemizedlist>
<para>The <literal>license</literal> 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 <literal>license</literal> actions. The length of the
license attribute value should not be more than 64 characters.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>must-accept</literal></term>
<listitem><para>When <literal>true</literal>, this license must be accepted
by a user before the related package can be installed or updated. Omission
of this attribute is equivalent to <literal>false</literal>. The method of
acceptance (interactive 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.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>must-display</literal></term>
<listitem><para>When <literal>true</literal>, the action's payload must be
displayed by clients during packaging operations. Omission of this value is
equivalent to <literal>false</literal>. 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.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2><title>Legacy Actions</title>
<para>The <literal>legacy</literal> 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
particular, this should be sufficient to convince the legacy system that the
package named by the <literal>pkg</literal> attribute is installed on the
system, so that the package can be used to satisfy dependencies.</para>
<para>The following attributes, named in accordance with the parameters on
<olink targetdoc="refman" targetptr="pkginfo-5"><citerefentry><refentrytitle>pkginfo</refentrytitle><manvolnum>5</manvolnum></citerefentry></olink>, are recognized:</para>
<variablelist termlength="wholeline">
<varlistentry><term><literal>category</literal></term>
<listitem><para>The value for the <literal>CATEGORY</literal> parameter. The
default value is <literal>system</literal>.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>desc</literal></term>
<listitem><para>The value for the <literal>DESC</literal> parameter.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>hotline</literal></term>
<listitem><para>The value for the <literal>HOTLINE</literal> parameter.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>name</literal></term>
<listitem><para>The value for the <literal>NAME</literal> parameter. The default
value is <literal>none provided</literal>.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>pkg</literal></term>
<listitem><para>The abbreviation for the package being installed. The default
value is the name from the FMRI of the package. This is a <literal>legacy</literal> action's
key attribute.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>vendor</literal></term>
<listitem><para>The value for the <literal>VENDOR</literal> parameter.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>version</literal></term>
<listitem><para>The value for the VERSION parameter. The default value is
the version from the FMRI of the package.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2><title>Set Actions</title>
<para>The <literal>set</literal> action represents a package-level attribute,
or metadata, such as the package description.</para>
<para>The following attributes are recognized:</para>
<variablelist>
<varlistentry><term><literal>name</literal></term>
<listitem><para>The name of the attribute.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>value</literal></term>
<listitem><para>The value given to the attribute.</para>
</listitem>
</varlistentry>
</variablelist>
<para>The <literal>set</literal> 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.</para>
<variablelist termlength="wholeline">
<varlistentry><term><literal>info.classification</literal></term>
<listitem><para>One or more tokens that a <literal>pkg</literal>(7) client
can use to classify the package. The value should have a scheme (such as &ldquo;org.opensolaris.category.2008&rdquo;
or &ldquo;org.acm.class.1998&rdquo;) and the actual classification, such as &ldquo;Applications/Games&rdquo;,
separated by a colon (:).</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>pkg.description</literal></term>
<listitem><para>A detailed description of the contents and functionality of
the package, typically a paragraph or so in length.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>pkg.fmri</literal></term>
<listitem><para>The name and version of the containing package. See
&ldquo;Package FMRIs and Versions&rdquo; in the &ldquo;Description&rdquo;
section.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>pkg.human-version</literal></term>
<listitem><para>The version scheme used by IPS is strict. See &ldquo;Package
FMRIs and Versions&rdquo; in the &ldquo;Description&rdquo; section. A more
flexible version can be provided as the value of the
<literal>pkg.human-version</literal> attribute. The value is displayed by IPS
tools such as <command>pkg info</command>, <command>pkg contents</command>, and
<command>pkg search</command>. The <literal>pkg.human-version</literal> value
is not used as a basis for version comparison and cannot be used in place of
the <literal>pkg.fmri</literal> version.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>pkg.obsolete</literal></term>
<listitem><para>When <literal>true</literal>, the package is marked obsolete.
An obsolete package can have no actions other than more set actions, and must
not be marked renamed.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>pkg.renamed</literal></term>
<listitem><para>When <literal>true</literal>, the package has been renamed.
There must be one or more <literal>depend</literal> 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.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>pkg.legacy</literal></term>
<listitem><para>When <literal>true</literal>, the package is marked legacy,
meaning that it will be removed in the future.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>pkg.summary</literal></term>
<listitem><para>A short, one-line description of the package.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2><title>Group Actions</title>
<para>The <literal>group</literal> action defines a UNIX group as defined
in <olink targetdoc="refman" targetptr="group-5"><citerefentry><refentrytitle>group</refentrytitle><manvolnum>5</manvolnum></citerefentry></olink>. No support is present for group passwords.
Groups defined with this action initially have no user list. Users can be
added with the <literal>user</literal> action.</para>
<para>A delivered <literal>group</literal> action, with or without associated 
<literal>facet</literal> or <literal>variant</literal> values, will override 
any <literal>group</literal> entry manually added to the system. Subsequent package removals or 
fixes will use the package definition for the <literal>group</literal>.</para>
<para>The following attributes are recognized:</para>
<variablelist termlength="wholeline">
<varlistentry><term><literal>groupname</literal></term>
<listitem><para>The value for the name of the group.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>gid</literal></term>
<listitem><para>The group's unique numerical id.
If not specified the first free value in the dynamic allocation range
100-499 in the install image is used.  The range 0-99 is reserved for
static allocation by the operating system vendor only.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2><title>User Actions</title>
<para>The <literal>user</literal> action defines a local account as defined in <filename>
/etc/passwd</filename>, <filename>/etc/shadow</filename>, <filename>/etc/group</filename>,
and <filename>/etc/ftpd/ftpusers</filename> files. Entries are added to the
appropriate files for users defined with this <literal>user</literal> action.</para>
<para>The <literal>user</literal> action is intended to define a user or role account for
use by a system commonent or application. The <literal>user</literal> action should not
be used for end user or administrator accounts.</para>
<para>A delivered <literal>user</literal> action, with or without associated 
<literal>facet</literal> or <literal>variant</literal> values, will override 
any <literal>user</literal> entry manually added to the system. Subsequent package removals or 
fixes will use the package definition for the <literal>user</literal>.</para>
<para>The following attributes are recognized:</para>
<variablelist termlength="wholeline">
<varlistentry><term><literal>username</literal></term>
<listitem><para>The unique name of the user</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>password</literal></term>
<listitem><para>The encrypted password of the user. Default value is <literal>*LK*
</literal>. See
<olink targetdoc="refman" targetptr="shadow-5"><citerefentry><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry></olink>.
</para>
<para>The special value "UP" can be used to indicate that the
<olink targetdoc="refman" targetptr="passwd-1"><citerefentry><refentrytitle>passwd</refentrytitle><manvolnum>1</manvolnum></citerefentry></olink> 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 <literal>pkg verify</literal>
will not report an unexpected change and <literal>pkg fix</literal> will not
change the value back to that of the manifest.</para>
<para>Best practice is to deliver role accounts with password="NP" and deliver a
<olink targetdoc="refman" targetptr="user-attr-5"><citerefentry><refentrytitle>user_attr</refentrytitle><manvolnum>5</manvolnum></citerefentry></olink> file that sets <literal>roleauth=user</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>uid</literal></term>
<listitem><para>The unique uid of the user.
If not specified the first free value in the dynamic allocation range:
100-499 in the install image is used.  The range 0-99 is reserved for
static allocation by the operating system vendor only.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>group</literal></term>
<listitem><para>The name of the user's primary group. Must be found in <filename>
/etc/group</filename>.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>gcos-field</literal></term>
<listitem><para>The value of the <literal>gcos</literal> field in <filename>/etc/passwd
</filename>. Default value is <literal>username</literal>.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>home-dir</literal></term>
<listitem><para>The user's home directory. This directory must be in the system
image directories and not under another mount point such as <filename>/home</filename>.
Default value is <literal>/</literal>.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>login-shell</literal></term>
<listitem><para>The user's default shell. Default value is empty.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>group-list</literal></term>
<listitem><para>Secondary groups to which the user belongs. See <olink targetdoc="refman" targetptr="group-5"><citerefentry><refentrytitle>group</refentrytitle><manvolnum>5</manvolnum></citerefentry></olink>.
</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>ftpuser</literal></term>
<listitem><para>Can be set to <literal>true</literal> or <literal>false</literal>.
The default value of <literal>true</literal> indicates that the user is permitted
to login via FTP. See <olink targetdoc="refman" targetptr="ftpusers-5"><citerefentry><refentrytitle>ftpusers</refentrytitle><manvolnum>5</manvolnum></citerefentry></olink>.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>lastchg</literal></term>
<listitem><para>The number of days between January 1, 1970, and the date that
the password was last modified. Default value is empty. See <olink targetdoc="refman" targetptr="shadow-5"><citerefentry><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry></olink>.
</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>min</literal></term>
<listitem><para>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 <olink targetdoc="refman" targetptr="shadow-5"><citerefentry><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry></olink>.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>max</literal></term>
<listitem><para>The maximum number of days the password is valid. Default
value is empty. See <olink targetdoc="refman" targetptr="shadow-5"><citerefentry><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry></olink>.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>warn</literal></term>
<listitem><para>The number of days before password expires that the user is
warned. See <olink targetdoc="refman" targetptr="shadow-5"><citerefentry><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry></olink>.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>inactive</literal></term>
<listitem><para>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 <filename>lastlog</filename> file. See <olink targetdoc="refman" targetptr="shadow-5"><citerefentry><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry></olink>.
</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>expire</literal></term>
<listitem><para>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 <olink targetdoc="refman" targetptr="shadow-5"><citerefentry><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry></olink>.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>flag</literal></term>
<listitem><para>Set to empty. See <olink targetdoc="refman" targetptr="shadow-5"><citerefentry><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry></olink>.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
</refsect1>
<refsect1 role="other"><title>Actuators</title>
<para>In certain contexts, additional operations can be appropriate to execute
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
<literal>/</literal> of the active, running boot environment of the current
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.</para>
<para>Incorrectly specified actuators can result in package installation failure
if the actuator cannot determine a means of making safe installation progress.</para>
<para>The following actuators are defined:</para>
<variablelist termlength="wholeline">
<varlistentry><term><literal>reboot-needed</literal></term>
<listitem><para>Can be set to <literal>true</literal> or <literal>false</literal>.
This actuator declares that update or removal of the tagged action must be
performed in a new boot environment if the package system is operating on
a live image. Creation of a new boot environment is controlled by the
<literal>be-policy</literal> image property. See the &ldquo;Image
Properties&rdquo; section in the <olink targetdoc="refman" targetptr="pkg-1"><citerefentry><refentrytitle>pkg</refentrytitle><manvolnum>1</manvolnum></citerefentry></olink> man page for more
information about the <literal>be-policy</literal> property.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>disable_fmri</literal>, <literal>refresh_fmri</literal>, <literal>restart_fmri</literal>, <literal>suspend_fmri</literal></term>
<listitem><para>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.</para>
<para>With <literal>disable_fmri</literal>, <literal>refresh_fmri</literal>, and
<literal>restart_fmri</literal>, 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 <command>svcs</command> command,
rather than implicitly by not indicating any instances.</para>
<para>If the same service FMRI is tagged by multiple actions, possibly in
multiple packages, the operation specified by that actuator is performed only
once. For example, if multiple <literal>restart_fmri</literal> actuators
specify the same FMRI, that service is restarted only one time for that
<command>pkg</command> operation.</para>
<para>The following list of SMF actuators describes the effect on the service
FMRI that is the value of each named actuator. In these descriptions,
&ldquo;uninstalling the package&rdquo; also includes moving the
<literal>file</literal> action that delivers the service to a different package.</para>
<variablelist termlength="wholeline">
<varlistentry><term><literal>disable_fmri</literal></term>
<listitem>
<para>Disable (<command>svcadm disable</command>) the specified service prior
to uninstalling the package.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>refresh_fmri</literal></term>
<listitem>
<para>Refresh (<command>svcadm refresh</command>) the specified service after
installing, updating, or uninstalling the package.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>restart_fmri</literal></term>
<listitem>
<para>Restart (<command>svcadm restart</command>) the specified service after
installing, updating, or uninstalling the package.</para>
</listitem>
</varlistentry>
<varlistentry><term><literal>suspend_fmri</literal></term>
<listitem>
<para>Temporarily disable (<command>svcadm disable -t</command>) the specified
service prior to updating the package, and then enable
(<command>svcadm enable</command>) the service after updating the package. The
specified service value must be a fully specified service instance FMRI (for
example, <literal>svc:/site/mysvc:default</literal> instead of
<literal>svc:/site/mysvc</literal>) and cannot include globbing characters.
<literal>suspend_fmri</literal> can be performed only on services that are
enabled and applies only to package update operations.</para>
</listitem>
</varlistentry>
</variablelist>
<para>SMF actuators are not executed in the following cases:</para>
<itemizedlist>
<listitem>
<para>When operating on an alternate root (<command>pkg -R /<replaceable>path</replaceable>/<replaceable>to</replaceable>/<replaceable>BE</replaceable></command>).</para>
</listitem>
<listitem>
<para>When recursing from the global zone (<command>pkg <replaceable>subcommand</replaceable> -r</command>).</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="other"><title>Mediations</title>
<para>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 &ldquo;Link Actions&rdquo; for information about mediator
attributes.</para>
<para>The following example shows two different instances of a mediator named <literal>
java</literal> where the link choices are between versions. These two <literal>link
</literal> actions would appear in two different packages.</para>
<programlisting>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</programlisting>
<para>See the <command>set-mediator</command> subcommand in the <olink targetdoc="refman" targetptr="pkg-1"><citerefentry><refentrytitle>pkg</refentrytitle><manvolnum>1</manvolnum></citerefentry></olink>
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.</para>
</refsect1>
<refsect1 role="other"><title>Constraints and Freezing</title>
<para>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.</para>
<para>The most common form of constraint is delivered by the <literal>require</literal> dependency,
as described in &ldquo;Depend Actions&rdquo; above. Such a constraint prevents
the package from being downgraded or removed.</para>
<para>Most parts of the operating system are encapsulated by packages called <emphasis>
incorporations</emphasis>. These packages primarily deliver constraints represented
by the <literal>incorporate</literal> dependency.</para>
<para>As described above, an incorporated package need not be present on the
system, but if it is, then it specifies both an inclusive minimum version
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 satisfy 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.</para>
<para>Incorporations are used to force parts of the system to upgrade synchronously.
For some components, such as the C library and the kernel, this is a basic
requirement. For others, such as a simple userland component 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.</para>
<para>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.</para>
<para>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 constraint. 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.</para>
<para>A system administrator can constrain a package by using the
<command>pkg freeze</command> command. The named package is constrained to the version
installed on the system if no version is provided. If a versioned package
is provided, then this administrative constraint, or freeze, acts as if an
incorporate dependency were installed where the <literal>fmri</literal> attribute
had the value of the provided package version.</para>
<para>A freeze is never lifted automatically by the packaging system. To relax
a constraint, use the <command>pkg unfreeze</command> command.</para>
</refsect1>
<refsect1 role="other"><title>Publishers and Repositories</title>
<para>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.</para>
<para>An <emphasis>origin</emphasis> 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 <command>pkgsend</command> or <command>
pkgrecv</command> is used on a package repository.</para>
<para>A <emphasis>mirror</emphasis> 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
content 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 sharing among a trusted set
of clients using the dynamic mirror functionality of <olink targetdoc="refman" targetptr="pkg.depotd-8"><citerefentry><refentrytitle>pkg.depotd</refentrytitle><manvolnum>8</manvolnum></citerefentry></olink>.
Mirrors are also intended to be used to authenticate access to package metadata,
but distribute the package content without authentication. For example, a
client might be configured with an <literal>https</literal> origin that requires
an SSL key and certificate pair to access, and with an <literal>http</literal> 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 <filename>file</filename> and their parents.
An origin repository can be also be provisioned as a mirror by using the mirror
mode of <olink targetdoc="refman" targetptr="pkg.depotd-8"><citerefentry><refentrytitle>pkg.depotd</refentrytitle><manvolnum>8</manvolnum></citerefentry></olink>.</para>
</refsect1>
<refsect1 role="other"><title>Global and Non-Global Zone Update</title>
<para>The <literal>pkg</literal> system forces non-global zones to be kept
in sync with the global zone. This means that certain packages must be at
the same version in the global zone and all non-global zones to ensure the
same kernel is run. To do this, <literal>pkg</literal> uses <literal>parent</literal> dependencies
to impose certain constraints on non-global zones. See &ldquo;Depend Actions&rdquo;
above for more information about <literal>parent</literal> dependencies.</para>
<para>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 <emphasis role="strong">system repository</emphasis> (see
the <olink targetdoc="refman" targetptr="pkg.sysrepo-8"><citerefentry><refentrytitle>pkg.sysrepo</refentrytitle><manvolnum>8</manvolnum></citerefentry></olink> 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 publishers are ranked
higher in the publisher search order than publishers configured in the non-global
zone. See the <command>pkg set-publisher</command> command in the <olink targetdoc="refman" targetptr="pkg-1"><citerefentry><refentrytitle>pkg</refentrytitle><manvolnum>1</manvolnum></citerefentry></olink>
man page for information about publisher search order.</para>
<para>To update all non-global zones on the system, use the <command>pkg update</command> command
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 <literal>foo</literal> 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 <literal>foo</literal> has a parent
dependency, then <command>pkg update foo</command> updates <literal>foo</literal> to
version 2 in both the global zone and the non-global zones because the <literal>parent
</literal> dependency forces the package to stay in sync. If <literal>foo</literal> does
not have a parent dependency, then <literal>foo</literal> is updated to version
2 in the global zone but remains at version 1 in the non-global zones.</para>
</refsect1>
<refsect1 role="other"><title>Facets and Variants</title>
<para>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.</para>
<para>In IPS, optional components are called <emphasis>facets</emphasis> and
mutually exclusive components are called <emphasis>variants</emphasis>. 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. Examples of components with multiple facet and variant tags include
an architecture-specific header file that is used by developers, or a component
that is only for a SPARC global zone.</para>
<para>An example of a variant tag is <literal>variant.arch=sparc</literal>.
An example of a facet tag is <literal>facet.devel=true</literal>. Facets and
variants are often referred to without the leading <literal>facet.</literal> and <literal>
variant.</literal>.</para>
<para>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 <command>pkg facet</command> and <command>pkg variant</command> commands
as shown in the <olink targetdoc="refman" targetptr="pkg-1"><citerefentry><refentrytitle>pkg</refentrytitle><manvolnum>1</manvolnum></citerefentry></olink> man page. To modify the values of
the facets and variants set on the image, use the <command>pkg change-facet</command> and <command>
pkg change-variant</command> commands.</para>
<para>Facets are treated as boolean values by package clients: Facets can
be set only to <literal>true</literal> (enabled) or <literal>false</literal> (disabled)
in the image. By default, all facets starting with 'facet.debug.' or 'facet.optional.' are considered
to be set to <literal>false</literal> in the image; all others are considered to be set to <literal>true</literal>
in the image.</para>
<para>Facets can be either set locally within an image using the <command>pkg change-facet</command> 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
<command>pkg change-facet</command> command only affect locally set facets. Inherited facets can only be changed by making the change in the parent image. By default, the <command>pkg facet</command> command does not display masked facets.</para>
<para>The value of a facet tag on an action can be set to <literal>all</literal> or
<literal>true</literal> to control how clients filter faceted actions. All values other than
<literal>all</literal> or <literal>true</literal> have undefined behavior. See below for a
description of the conditions that must exist in the image to install an action that has facet
tags.</para>
<para>The <literal>all</literal> value for a facet is useful when more than
a single level of filtering is required. In the following example, <literal>foo.txt
</literal> is installed only if the <literal>doc</literal> facet and at least
one of the <literal>locale</literal> facets is <literal>true</literal> in
the image. This enables administrators to exclude documentation, but still
enable or disable support for specific locales. In addition, <literal>api.txt</literal> is
only installed if both the <literal>doc</literal> and <literal>devel</literal> facets
are <literal>true</literal> in the image.</para>
<programlisting>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</programlisting>
<para>A facet set on the image can be a full facet such as <literal>doc.man</literal> or
a pattern such as <literal>locale.*</literal>. This is useful when you want
to disable a portion 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:</para>
<screen># <userinput>pkg change-facet locale.*=false</userinput>
[output about packages being updated]
# <userinput>pkg change-facet locale.en_US=true</userinput>
[output about packages being updated]</screen>
<para>Most variants can have any number of values. For example, the
<literal>arch</literal> variant can be set to <literal>i386</literal>,
<literal>sparc</literal>, <literal>ppc</literal>, <literal>arm</literal>, or
whatever architectures the distribution
supports. (Only <literal>i386</literal> and <literal>sparc</literal> are used
in Oracle Solaris.) The exception are the <literal>debug</literal> variants.
The <literal>debug</literal> variants should only be set to <literal>true</literal>
or <literal>false</literal>; other values have undefined behavior. If a file
action has both non-debug and debug versions, both versions must have the
applicable <literal>debug</literal> variant explicitly set, as shown in the
following example:</para>
<programlisting>file group=sys mode=0644 overlay=allow owner=root &bsol;
  path=etc/motd pkg.csize=115 pkg.size=103 preserve=true &bsol;
  variant.debug.osnet=true

file group=sys mode=0644 overlay=allow owner=root &bsol;
  path=etc/motd pkg.csize=68 pkg.size=48 preserve=true &bsol;
  variant.debug.osnet=false</programlisting>
<para>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
<literal>arch</literal> and <literal>zone</literal> variants are set by the
program that creates the image and installs its initial contents.</para>
<itemizedlist>
<para>The facets and variants set on the image affect whether a particular
action is installed.</para>
<listitem><para>Actions with no facet or variant tags are always installed.</para>
</listitem>
<listitem><para>Actions with facet tags are installed if the following
conditions exist in the image:</para>
<itemizedlist>
<listitem><para>All facet tags on the action that have a value of
<literal>all</literal> are <literal>true</literal> in the image
(<literal>false</literal> is the default for all facets starting with 'facet.debug.'
or 'facet.optional.'; <literal>true</literal> is the default for all others).</para>
</listitem>
<listitem><para>If any facet tags on the action have a value of
<literal>true</literal>, at least one of those facets is <literal>true</literal>
in the image.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem><para>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.</para>
</listitem>
<listitem><para>Actions with both facet and variant tags are installed if
both the facets and the variants allow the action to be installed.</para>
</listitem>
<listitem><para>Both user and group actions can also be controlled by
facets and variants. If any facet tags on the action have a value of
<literal>true</literal>, then the user or group will be present.
And if the values of all the variant tags are the same as the values set in
the image, then the user or group will be present.</para>
</listitem>
</itemizedlist>
<para>You can create custom facet tags and variant tags. See
<olink targetdoc="PKDEV"><citetitle remap="book">Packaging and Delivering Software With the Image Packaging System in Oracle Solaris 11.4</citetitle></olink> for more information. The following tags are in common use in Oracle Solaris.</para>
<informaltable frame="topbot">
<textobject><simpara>Variants and their possible values.</simpara></textobject>
<tgroup cols="2" colsep="0" rowsep="0"><colspec colwidth="50*"/><colspec
colwidth="50*"/><thead>
<row rowsep="1">
<entry>
<para>Variant Name</para>
</entry>
<entry>
<para>Possible Values</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<para><literal>variant.arch</literal></para>
</entry>
<entry>
<para><literal>sparc</literal>, <literal>i386</literal></para>
</entry>
</row>
<row>
<entry>
<para><literal>variant.opensolaris.zone</literal></para>
</entry>
<entry>
<para><literal>global</literal>, <literal>nonglobal</literal></para>
</entry>
</row>
<row>
<entry>
<para><literal>variant.debug.*</literal></para>
</entry>
<entry>
<para><literal>true</literal>, <literal>false</literal></para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>The following list shows a small sample of the facet tags that are used
in Oracle Solaris:</para>
<programlisting>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</programlisting>
</refsect1>
<refsect1 role="other"><title>Image Policies</title>
<para>Image policies are defined by image properties with boolean values.
See &ldquo;Image Properties&rdquo; in the <olink targetdoc="refman" targetptr="pkg-1"><citerefentry><refentrytitle>pkg</refentrytitle><manvolnum>1</manvolnum></citerefentry></olink> man page
for descriptions of the <literal>flush-content-cache-on-success</literal> and <literal>
send-uuid</literal> properties and information about how to view and modify
their values.</para>
</refsect1>
<refsect1 role="files"><title></title>
<para>Since <literal>pkg</literal>(7) images can be located arbitrarily within
a larger file system, the token <literal>$IMAGE_ROOT</literal> is used to
distinguish relative paths. For a typical system installation, <literal>$IMAGE_ROOT
</literal> is equivalent to /.</para>
<variablelist termlength="wholeline">
<varlistentry><term><filename>$IMAGE_ROOT/var/pkg</filename></term>
<listitem><para>Metadata directory for a full or partial image.</para>
</listitem>
</varlistentry>
<varlistentry><term><filename>$IMAGE_ROOT/.org.opensolaris,pkg</filename></term>
<listitem><para>Metadata directory for a user image.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Within the metadata of a particular image, certain files and directories
can contain information useful during repair and recovery. The token <literal>$IMAGE_META
</literal> is used to refer to the top-level directory that contains the metadata. <literal>
$IMAGE_META</literal> is typically one of the two paths given above.</para>
<variablelist termlength="wholeline">
<varlistentry><term><filename>$IMAGE_META/lost+found</filename></term>
<listitem><para>Location of conflicting directories and files moved during
a package operation.</para>
</listitem>
</varlistentry>
<varlistentry><term><filename>$IMAGE_META/publisher</filename></term>
<listitem><para>Contains a directory for each publisher. Each directory stores
publisher-specific metadata.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Other paths within the <literal>$IMAGE_META</literal> directory hierarchy
are Private, and are subject to change.</para>
</refsect1>
<refsect1 role="attributes"><title></title>
<para>See <olink targetdoc="refman" targetptr="attributes-7"><citerefentry><refentrytitle>attributes</refentrytitle><manvolnum>7</manvolnum></citerefentry></olink> for descriptions of the following
attributes:</para>
<informaltable frame="all" orient="port">
<textobject>
<simpara>Table shows applicable attribute types and related values.</simpara>
</textobject>
<tgroup cols="2" colsep="1" rowsep="1"><colspec colname="col1" colwidth="198*"
align="left"/><colspec colname="col2" colwidth="198*" align="left"/><thead>
<row>
<entry align="center">
<para>ATTRIBUTE TYPE</para>
</entry>
<entry align="center">
<para>ATTRIBUTE VALUE</para>
</entry>
</row>
</thead>
<tbody>
<row>
<entry align="left">
<para>Availability</para>
</entry>
<entry align="left">
<para><literal>package/pkg</literal></para>
</entry>
</row>
<row>
<entry align="left">
<para>Interface Stability</para>
</entry>
<entry align="left">
<para>Uncommitted</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable></refsect1>
<refsect1 role="see-also"><title></title>
<para><olink targetdoc="refman" targetptr="pkg-1"><citerefentry><refentrytitle>pkg</refentrytitle><manvolnum>1</manvolnum></citerefentry></olink>,
<olink targetdoc="refman" targetptr="pkgdepend-1"><citerefentry><refentrytitle>pkgdepend</refentrytitle><manvolnum>1</manvolnum></citerefentry></olink>,
<olink targetdoc="refman" targetptr="pkgdiff-1"><citerefentry><refentrytitle>pkgdiff</refentrytitle><manvolnum>1</manvolnum></citerefentry></olink>,
<olink targetdoc="refman" targetptr="pkgfmt-1"><citerefentry><refentrytitle>pkgfmt</refentrytitle><manvolnum>1</manvolnum></citerefentry></olink>,
<olink targetdoc="refman" targetptr="pkglint-1"><citerefentry><refentrytitle>pkglint</refentrytitle><manvolnum>1</manvolnum></citerefentry></olink>,
<olink targetdoc="refman" targetptr="pkgmerge-1"><citerefentry><refentrytitle>pkgmerge</refentrytitle><manvolnum>1</manvolnum></citerefentry></olink>,
<olink targetdoc="refman" targetptr="pkgmogrify-1"><citerefentry><refentrytitle>pkgmogrify</refentrytitle><manvolnum>1</manvolnum></citerefentry></olink>,
<olink targetdoc="refman" targetptr="pkgrecv-1"><citerefentry><refentrytitle>pkgrecv</refentrytitle><manvolnum>1</manvolnum></citerefentry></olink>,
<olink targetdoc="refman" targetptr="pkgrepo-1"><citerefentry><refentrytitle>pkgrepo</refentrytitle><manvolnum>1</manvolnum></citerefentry></olink>,
<olink targetdoc="refman" targetptr="pkgsend-1"><citerefentry><refentrytitle>pkgsend</refentrytitle><manvolnum>1</manvolnum></citerefentry></olink>,
<olink targetdoc="refman" targetptr="pkgsign-1"><citerefentry><refentrytitle>pkgsign</refentrytitle><manvolnum>1</manvolnum></citerefentry></olink>,
<olink targetdoc="refman" targetptr="pkgsurf-1"><citerefentry><refentrytitle>pkgsurf</refentrytitle><manvolnum>1</manvolnum></citerefentry></olink>,
<olink targetdoc="refman" targetptr="pkg.depotd-8"><citerefentry><refentrytitle>pkg.depotd</refentrytitle><manvolnum>8</manvolnum></citerefentry></olink>,
<olink targetdoc="refman" targetptr="pkg.sysrepo-8"><citerefentry><refentrytitle>pkg.sysrepo</refentrytitle><manvolnum>8</manvolnum></citerefentry></olink>,
<olink targetdoc="refman" targetptr="svcs-1"><citerefentry><refentrytitle>svcs</refentrytitle><manvolnum>1</manvolnum></citerefentry></olink>,
<olink targetdoc="refman" targetptr="svcadm-8"><citerefentry><refentrytitle>svcadm</refentrytitle><manvolnum>8</manvolnum></citerefentry></olink></para>
<para><olink targetdoc="AUOSS"><citetitle remap="book">Updating Systems and Adding Software in Oracle Solaris 11.4</citetitle></olink></para>
<para><olink targetdoc="CCOSP"><citetitle remap="book">Creating Package Repositories in Oracle Solaris 11.4</citetitle></olink></para>
<para><olink targetdoc="PKDEV"><citetitle remap="book">Packaging and Delivering Software With the Image Packaging System in Oracle Solaris 11.4</citetitle></olink></para>
<para><literal>https://github.com/oracle/solaris-ips</literal></para>
</refsect1>
</refentry>