'\" te
.\" Copyright 2017 Peter Tribble
.\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright 1989 AT&T
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH PKGINFO 5 "Nov 26, 2017"
.SH NAME
pkginfo \- package characteristics file
.SH DESCRIPTION
.LP
\fBpkginfo\fR is an \fBASCII\fR file that describes the characteristics of the
package along with information that helps control the flow of installation. It
is created by the software package developer.
.sp
.LP
Each entry in the \fBpkginfo\fR file is a line that establishes the value of a
parameter in the following form:
.sp
.in +2
.nf
PARAM="\fIvalue\fR"
.fi
.in -2

.sp
.LP
There is no required order in which the parameters must be specified within the
file. The \fBPKG\fR, \fBNAME\fR, \fBARCH\fR, \fBVERSION\fR and \fBCATEGORY\fR
parameters are mandatory. Other parameters are optional.
.sp
.LP
\fBpkginfo\fR provides optional parameters and an environment variable in
support of the zones (multiple Solaris environments) feature. See
\fBzones\fR(7).
.sp
.LP
The following parameters are mandatory:
.sp
.ne 2
.na
\fB\fBARCH\fR\fR
.ad
.sp .6
.RS 4n
A comma-separated list of alphanumeric tokens that indicate the architecture
associated with the package. The \fBpkgmk\fR(1) tool can be used to create or
modify this value when actually building the package. The maximum length of a
token is 16 characters and it cannot include a comma.
.sp
Solaris's installation software meaningfully uses only one architecture token
of the form:
.sp
.in +2
.nf
<\fIinstruction_set_architecture\fR>[.<\fIplatform_group\fR>]
.fi
.in -2

where \fIplatform_group\fR is intended only for Solaris installation packages.
Third party application software should restrict itself to \fBARCH\fR values
from the following Solaris-supported instruction set architectures (\fBuname
-p\fR): \fBsparc\fR, \fBi386\fR, and \fBppc\fR. Examples of Solaris' platform
groups (\fBuname -m\fR) are \fBsun4u\fR for the \fBSPARC\fR instruction set and
\fBi86pc\fR for the i386 instruction set. See \fBuname\fR(1) and
\fBisalist\fR(1) for more details.
.RE

.sp
.ne 2
.na
\fB\fBCATEGORY\fR\fR
.ad
.sp .6
.RS 4n
A comma-separated list of categories under which a package can be displayed. A
package must at least belong to the system or application category. Categories
are case-insensitive and can contain only alphanumerics. Each category is
limited in length to 16 characters.
.RE

.sp
.ne 2
.na
\fB\fBNAME\fR\fR
.ad
.sp .6
.RS 4n
Text that specifies the package name (maximum length of 256 \fBASCII\fR
characters). Use the \fBNAME\fR parameter as the foundation for describing the
functionality and purpose of the package; spell out any acronyms and avoid
internal product/project code names. The \fBDESC\fR parameter can then be used
to expand the descriptive information. Use the \fBNAME\fR parameter to state as
specifically as possible the use of the package, why a user would need to load
it, and so on.
.RE

.sp
.ne 2
.na
\fB\fBPKG\fR\fR
.ad
.sp .6
.RS 4n
Abbreviation for the package being installed. All characters in the
abbreviation must be alphanumeric. You can also use the \fB\(mi\fR and \fB+\fR
characters in the abbreviation. The first character cannot be numeric, a
\fB+\fR or a \fB-\fR.
.sp
The abbreviation is limited to a maximum length of 32 characters.
\fBinstall\fR, \fBnew\fR, and \fBall\fR are reserved abbreviations. It is
customary to make the first four letters unique to your company, such as the
company's stock symbol.
.RE

.sp
.ne 2
.na
\fB\fBVERSION\fR\fR
.ad
.sp .6
.RS 4n
Text that specifies the current version associated with the software package.
The maximum length is 256 \fBASCII\fR characters and the first character cannot
be a left parenthesis. The \fBpkgmk\fR(1) tool can be used to create or modify
this value when actually building the package. Traditional Solaris
practice was to assign this parameter monotonically increasing Dewey decimal
values of the form:
.sp
.in +2
.nf
<\fImajor_revision\fR>.<\fIminor_revision\fR>[.<\fImicro_revision\fR>]
.fi
.in -2

where all the revision fields are integers. The versioning fields can be
extended to an arbitrary string of numbers in Dewey-decimal format, if
necessary.
.RE

.sp
.LP
The following parameters are optional:
.sp
.ne 2
.na
\fB\fBBASEDIR\fR\fR
.ad
.sp .6
.RS 4n
The pathname to a default directory where "relocatable" files can be installed.
If blank, the package is not relocatable and any files that have relative
pathnames are not installed. An administrator can override the default
directory.
.RE

.sp
.ne 2
.na
\fB\fBCLASSES\fR\fR
.ad
.sp .6
.RS 4n
A space-separated list of classes defined for a package. The order of the list
determines the order in which the classes are installed. Classes listed first
are installed first (on a media by media basis). This parameter can be modified
by the request script.
.RE

.sp
.ne 2
.na
\fB\fBDESC\fR\fR
.ad
.sp .6
.RS 4n
Text that describes the package (maximum length of 256 \fBASCII\fR characters).
This parameter value is used to provide the installer with a description of
what the package contains and should build on the description provided in the
\fBNAME\fR parameter. Try to make the two parameters work together so that a
\fBpkginfo\fR \fB-l\fR provides a fairly comprehensive textual description of
the package.
.RE

.sp
.ne 2
.na
\fB\fBEMAIL\fR\fR
.ad
.sp .6
.RS 4n
An electronic address where further information is available or bugs can be
reported (maximum length of 256 \fBASCII\fR characters).
.RE

.sp
.ne 2
.na
\fB\fBHOTLINE\fR\fR
.ad
.sp .6
.RS 4n
Phone number and/or mailing address where further information can be received
or bugs can be reported (maximum length of 256 \fBASCII\fR characters).
.RE

.sp
.ne 2
.na
\fB\fBINTONLY\fR\fR
.ad
.sp .6
.RS 4n
Indicates that the package should only be installed interactively when set to
any non-null value.
.RE

.sp
.ne 2
.na
\fB\fBISTATES\fR\fR
.ad
.sp .6
.RS 4n
A list of allowable run states for package installation (for example, "\fBS s
1\fR" allows run states of \fBS\fR, \fBs\fR or \fB1\fR). The Solaris operating
environment supports the run levels \fBs\fR, \fBS\fR, \fB0\fR, \fB1\fR,
\fB2\fR, \fB3\fR, \fB5\fR, and \fB6\fR. Applicable run levels for this
parameter are \fBs\fR, \fBS\fR, \fB1\fR, \fB2\fR, and \fB3\fR. See
\fBinit\fR(8) for details.
.RE

.sp
.ne 2
.na
\fB\fBMAXINST\fR\fR
.ad
.sp .6
.RS 4n
The maximum number of package instances that should be allowed on a machine at
the same time. By default, only one instance of a package is allowed. This
parameter must be set in order to have multiple instances of a package. In
order to support multiple instances of packages (for example, packages that
differ in their \fBARCH\fR or \fBVERSION\fR parameter value), the value of this
parameter must be high enough to allow for all instances of a given package,
including multiple versions coexisting on a software server.
.RE

.sp
.ne 2
.na
\fB\fBORDER\fR\fR
.ad
.sp .6
.RS 4n
A list of classes defining the order in which they should be put on the medium.
Used by \fBpkgmk\fR(1) in creating the package. Classes not defined in this
field are placed on the medium using the standard ordering procedures.
.RE

.sp
.ne 2
.na
\fB\fBPSTAMP\fR\fR
.ad
.sp .6
.RS 4n
Production stamp used to mark the \fBpkgmap\fR(5) file on the output volumes.
Provides a means for distinguishing between production copies of a version if
more than one is in use at a time. If \fBPSTAMP\fR is not defined, the default
is used. The default consists of the UNIX system machine name followed by the
string "\fIYYYYMMDDHHMMSS\fR" (year, month, date, hour, minutes, seconds).
.RE

.sp
.ne 2
.na
\fB\fBRSTATES\fR\fR
.ad
.sp .6
.RS 4n
A list of allowable run states for package removal (for example, "\fBS s 1\fR"
allows run states of \fBS\fR, \fBs\fR or \fB1\fR). The Solaris operating
environment supports the run levels \fBs\fR, \fBS\fR, \fB0\fR, \fB1\fR,
\fB2\fR, \fB3\fR, \fB5\fR, and \fB6\fR. Applicable run levels for this
parameter are \fBs\fR, \fBS\fR, \fB1\fR, \fB2\fR, and \fB3\fR See
\fBinit\fR(8) for details.
.RE

.sp
.ne 2
.na
\fB\fBSUNW_ISA\fR\fR
.ad
.sp .6
.RS 4n
Solaris-only optional parameter that indicates a software package contains
64-bit objects if it is set to \fBsparcv9\fR. If this parameter is not set, the
default \fBISA\fR (instruction set architecture) is set to the value of the
\fBARCH\fR parameter.
.RE

.sp
.ne 2
.na
\fB\fBSUNW_PKG_DIR\fR\fR
.ad
.sp .6
.RS 4n
A value set by \fBpkgadd\fR that contains the location of the installing
package. This value is provided to any install time package procedure scripts
that need to know where the installing package is located. This parameter
should never be set manually from within a \fBpkginfo\fR file.
.RE

.sp
.ne 2
.na
\fB\fBSUNW_PKG_ALLZONES\fR\fR
.ad
.sp .6
.RS 4n
Defines whether a package, when installed, must be installed and must be
identical in all zones. Assigned value can be \fBtrue\fR or \fBfalse\fR. The
default value is \fBfalse\fR. The setting of \fBSUNW_PKG_ALLZONES\fR has the
effects described below.
.sp
If set to \fBtrue\fR, the following conditions are in effect:
.RS +4
.TP
.ie t \(bu
.el o
The package must be installed in the global zone.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The package must be installed in any non-global zone that is created.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The package must be identical in all zones.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The package can be installed only by the global zone administrator.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The package cannot be installed by a non-global zone administrator.
.RE
If set to \fBfalse\fR, the following conditions are in effect:
.RS +4
.TP
.ie t \(bu
.el o
The package is not required to be installed in all zones.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The package is not required to be identical across all zones.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The package can be installed by the global zone administrator or by a
non-global zone administrator.
.RE
Packages that must be identical across all zones must set this variable to
\fBtrue\fR. This would include packages that deliver components that are part
of the core operating system, or that are dependent on interfaces exported by
the core operating system, or that deliver device drivers, or runtime libraries
that use or export operating system interfaces that are not guaranteed to be
stable across minor releases.
.sp
Packages that deliver components that are not part of the core operating system
(such as application programs) that can be different between any two zones must
set this variable to \fBfalse\fR.
.sp
With respect to \fBSUNW_PKG_ALLZONES\fR, keep in mind the following:
.RS +4
.TP
.ie t \(bu
.el o
Use of \fBpkgadd\fR in the global zone installs packages in all zones unless
\fB-G\fR is specified, in which case packages are installed in the global zone
only. The setting of \fBSUNW_PKG_ALLZONES\fR does not change this behavior. For
example, a package that has a setting of \fBSUNW_PKG_ALLZONES=false\fR is not
installed in the global zone only.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The \fBSUNW_PKG_ALLZONES\fR attribute controls whether a package \fBmust\fR be
installed in all zones (and must be the same in all zones) when it is
installed.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Use of the \fB-G\fR option to \fBpkgadd\fR with a package that has
\fBSUNW_PKG_ALLZONES=true\fR is an error and causes installation of that
package to fail.
.RE
.RE

.sp
.ne 2
.na
\fB\fBSUNW_PKG_HOLLOW\fR\fR
.ad
.sp .6
.RS 4n
Defines whether a package should be visible in any non-global zone if that
package is required to be installed and be identical in all zones (for example,
a package that has \fBSUNW_PKG_ALLZONES=true\fR). Assigned value can be
\fBtrue\fR or \fBfalse\fR. The default value is \fBfalse\fR. The package is not
required to be installed, but if it is installed, the setting of
\fBSUNW_PKG_HOLLOW\fR has the effects described below.
.sp
If set to \fBfalse\fR, the following conditions are in effect:
.RS +4
.TP
.ie t \(bu
.el o
If installed in the global zone, the package content and installation
information are required in all non-global zones.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Software delivered by the package is visible in all non-global zones. An
example of such a a package is the package that delivers the \fBtruss\fR(1)
command.
.RE
If set to \fBtrue\fR, the following conditions are in effect:
.RS +4
.TP
.ie t \(bu
.el o
The package content is not delivered on any non-global zone. However, the
package installation information is required on all non-global zones.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The package delivers software that should not be visible in all non-global
zones. Examples include kernel drivers and system configuration files that work
only in the global zone. This setting allows the non-global zone to resolve
dependencies on packages that are installed only in the global zone without
actually installing the package data.
.RE
.RS +4
.TP
.ie t \(bu
.el o
In the global zone, the package is recognized as having been installed, and all
components of the package are installed. Directories are created, files are
installed, and class action and other scripts are run as appropriate when the
package is installed.
.RE
.RS +4
.TP
.ie t \(bu
.el o
In a non-global zone, the package is recognized as having been installed, but
no components of the package are installed. No directories are created, no
files are installed, and no class action or other install scripts are run when
the package is installed.
.RE
.RS +4
.TP
.ie t \(bu
.el o
When removed from the global zone, the package is recognized as having been
completely installed. Appropriate directories and files are removed, and class
action or other install scripts are run when the package is removed.
.RE
.RS +4
.TP
.ie t \(bu
.el o
When removed from a non-global zone, the package is recognized as not having
been completely installed. No directories are removed, no files are removed,
and no class action or other install scripts are run when the package is
removed.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The package is recognized as being installed in all zones for purposes of
dependency checking by other packages that rely on this package being
installed.
.RE
If \fBSUNW_PKG_ALLZONES\fR is set to \fBfalse\fR, the value of this variable
has no meaning. It is a package construction error to set
\fBSUNW_PKG_ALLZONES\fR to \fBfalse\fR, then set \fBSUNW_PKG_HOLLOW\fR to
\fBtrue\fR.
.RE

.sp
.ne 2
.na
\fB\fBSUNW_PKG_THISZONE\fR\fR
.ad
.sp .6
.RS 4n
Defines whether a package must be installed in the current zone only. Assigned
value can be \fBtrue\fR or \fBfalse\fR. The default value is \fBfalse\fR. The
setting of \fBSUNW_PKG_THISZONE\fR has the effects described below.
.sp
If set to true, the following conditions are in effect:
.RS +4
.TP
.ie t \(bu
.el o
The package is installed in the current zone only.
.RE
.RS +4
.TP
.ie t \(bu
.el o
If installed in the global zone, the package is not added to any currently
existing or yet-to-be-created non-global zones. This is the same behavior that
would occur if the \fB-G\fR option were specified to \fBpkgadd\fR.
.RE
If set to false, the following conditions are in effect:
.RS +4
.TP
.ie t \(bu
.el o
If \fBpkgadd\fR is run in a non-global zone, the package is installed in the
current zone only.
.RE
.RS +4
.TP
.ie t \(bu
.el o
If \fBpkgadd\fR is run in the global zone, the package is installed in the
global zone, and is also installed in all currently installed non-global zones.
In addition, the package will be propagated to all future, newly installed
non-global zones.
.RE
.RE

.sp
.ne 2
.na
\fB\fBSUNW_PKGVERS\fR\fR
.ad
.sp .6
.RS 4n
Solaris-only parameter indicating of version of the Solaris operating
environment package interface.
.sp
.in +2
.nf
SUNW_PKGVERS="<\fIsunw_package_version\fR>"
.fi
.in -2

where <\fIsunw_package_version\fR> has the form \fIx.y[.z]\fR and \fIx\fR,
\fIy\fR, and z are integers. For packages built for this release and previous
releases, use \fBSUNW_PKGVERS="\fI1.0\fR"\fR.
.RE

.sp
.ne 2
.na
\fB\fBSUNW_PRODNAME\fR\fR
.ad
.sp .6
.RS 4n
Solaris-only parameter indicating the name of the product this package is a
part of or comprises (maximum length of 256 \fBASCII\fR characters). A few
examples of \fBSUNW_PRODNAME\fR values are: \fB"SunOS"\fR,
\fB"OpenWindows"\fR, and \fB"Common Desktop Environment"\fR.
.RE

.sp
.ne 2
.na
\fB\fBSUNW_PRODVERS\fR\fR
.ad
.sp .6
.RS 4n
Solaris-only parameter indicating the version or release of the product
described in \fBSUNW_PRODNAME\fR (maximum length of 256 \fBASCII\fR
characters). For example, where \fBSUNW_PRODNAME="\fR\fISunOS\fR\fB"\fR, and
the Solaris 2.x Beta release, this string could be \fB"5.x BETA"\fR, while for
the Solaris 2.x FCS release, the string would be \fB"5.x"\fR. For Solaris 10,
the string is \fB"5.10"\fR. If the \fBSUNW_PRODNAME\fR parameter is \fINULL\fR,
so should be the \fBSUNW_PRODVERS\fR parameter.
.RE

.sp
.ne 2
.na
\fB\fBULIMIT\fR\fR
.ad
.sp .6
.RS 4n
If set, this parameter is passed as an argument to the \fBulimit\fR(1) command
(see \fBlimit\fR(1)), which establishes the maximum size of a file during
installation.
.RE

.sp
.ne 2
.na
\fB\fBVENDOR\fR\fR
.ad
.sp .6
.RS 4n
Used to identify the vendor that holds the software copyright (maximum length
of 256 \fBASCII\fR characters).
.RE

.sp
.ne 2
.na
\fB\fBVSTOCK\fR\fR
.ad
.sp .6
.RS 4n
The vendor stock number, if any, that identifies this product (maximum length
of 256 \fBASCII\fR characters).
.RE

.sp
.LP
For further discussion of the zones-related parameters described above, see
\fISystem Administration Guide: Virtualization Using the Solaris Operating
System\fR.

.SH EXAMPLES
.LP
\fBExample 1 \fRA Sample \fBpkginfo\fR File
.sp
.LP
Here is a sample \fBpkginfo\fR file:

.sp
.in +2
.nf
SUNW_PRODNAME="SunOS"
SUNW_PRODVERS="5.5"
SUNW_PKG_ALLZONES=false
SUNW_PKG_HOLLOW=false
PKG="SUNWesu"
NAME="Extended System Utilities"
VERSION="11.5.1"
ARCH="sparc"
VENDOR="Sun Microsystems, Inc."
HOTLINE="Please contact your local service provider"
EMAIL=""
VSTOCK="0122c3f5566"
CATEGORY="system"
ISTATES="S 2"
RSTATES="S 2"
.fi
.in -2

.SH ATTRIBUTES
.LP
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	See entries below
_
PKG value	Evolving
_
VERSION value	Evolving
_
NAME value	Evolving
_
DESC value	Evolving
_
ARCH value	Evolving
_
CATEGORY value	Evolving
_
BASEDIR value	Evolving
_
ISTATES value	Evolving
_
RSTATES value	Evolving
_
MAXINST value	Evolving
_
SUNW_PKG_ALLZONES	Evolving
_
SUNW_PKG_HOLLOW	Evolving
_
SUNW_PKG_THISZONE	Evolving
_
SUNW_PRODNAME	Evolving
_
SUNW_PRODVERS	Evolving
_
SUNW_PKGVERS	Evolving
_
SUNW_PKG_DIR	Evolving
.TE

.SH SEE ALSO
.LP
.BR isalist (1),
.BR limit (1),
.BR pkgmk (1),
.BR uname (1),
.BR pkgmap (5),
.BR attributes (7),
.BR zones (7),
.BR init (8)
.sp
.LP
\fIApplication Packaging Developer\&'s Guide\fR
.sp
.LP
\fISystem Administration Guide: Virtualization Using the Solaris Operating
System\fR
.SH NOTES
.LP
Developers can define their own installation parameters by adding a definition
to this file. A developer-defined parameter must begin with a capital letter.
.sp
.LP
Trailing white space after any parameter value is ignored. For example,
\fBVENDOR="Sun Microsystems, Inc."\fR is the same as \fBVENDOR="Sun
Microsystems, Inc. "\fR.