pkg(1) Man Page
NAME
pkg - image packaging retrieval client
SYNOPSIS
/usr/bin/pkg [options] command [cmd_options] [operands]
/usr/bin/pkg install [-nvq] [--accept] [--licenses] [--no-index]
[--no-refresh] [--deny-new-be | --require-new-be] [--be-name name]
pkg_fmri_pattern ...
/usr/bin/pkg uninstall [-nrvq] [--no-index]
[--deny-new-be | --require-new-be] [--be-name name]
pkg_fmri_pattern ...
/usr/bin/pkg update [-fnvq] [--accept] [--be-name name]
[--deny-new-be | --require-new-be] [--licenses] [--no-index]
[--no-refresh]
/usr/bin/pkg refresh [--full] [publisher ...]
/usr/bin/pkg contents [-Hmr] [-a attribute=pattern ...]
[-o attribute ...] [-s sort_key] [-t action_type ...]
[pkg_fmri_pattern ...]
/usr/bin/pkg info [-lr] [--license] [pkg_fmri_pattern ...]
/usr/bin/pkg list [-Hafnsuv] [--no-refresh] [pkg_fmri_pattern ...]
/usr/bin/pkg search [-HIaflpr] [-o attribute ...] [-s repo_uri]
query
/usr/bin/pkg verify [-Hqv] [pkg_fmri_pattern ...]
/usr/bin/pkg fix [--accept] [--licenses] [pkg_fmri_pattern ...]
/usr/bin/pkg image-create [-FPUfz] [--force]
[--full|--partial|--user] [--zone] [-k ssl_key] [-c ssl_cert]
[--no-refresh] [--variant <variant_spec>=<instance> ...]
[-g uri|--origin=uri ...] [-m uri|--mirror=uri ...]
[--facet <facet_spec>=[True|False] ...]
(-p|--publisher) [<name>=]<repo_uri> dir
/usr/bin/pkg variant [-H] [<variant_spec>]
/usr/bin/pkg change-variant [-nvq] [--accept]
[--deny-new-be | --require-new-be] [--be-name name]
[--licenses] <variant_spec>=<instance> ...
/usr/bin/pkg facet [-H] [<facet_spec>]
/usr/bin/pkg change-facet [-nvq] [--accept] [--be-name name]
[--deny-new-be | --require-new-be]
[--licenses] <facet_spec>=[True|False|None] ...
/usr/bin/pkg set-property propname propvalue
/usr/bin/pkg add-property-value propname propvalue
/usr/bin/pkg remove-property-value propname propvalue
/usr/bin/pkg unset-property propname ...
/usr/bin/pkg property [-H] [propname ...]
/usr/bin/pkg set-publisher [-Ped] [-k ssl_key] [-c ssl_cert]
[-g origin_to_add|--add-origin=origin_to_add ...]
[-G origin_to_remove|--remove-origin=origin_to_remove ...]
[-m mirror_to_add|--add-mirror=mirror_to_add ...]
[-M mirror_to_remove|--remove-mirror=mirror_to_remove ...]
[-p repo_uri] [--enable] [--disable] [--no-refresh]
[--reset-uuid] [--non-sticky] [--sticky]
[--search-after=publisher] [--search-before=publisher]
[--approve-ca-cert=path_to_CA]
[--revoke-ca-cert=hash_of_CA_to_remove]
[--unset-ca-cert=hash_of_CA_to_remove]
[--set-property name_of_property=value]
[--add-property-value name_of_property=value_to_add]
[--remove-property-value name_of_property=value_to_remove]
[--unset-property name_of_property_to_delete]
[publisher]
/usr/bin/pkg unset-publisher publisher ...
/usr/bin/pkg publisher [-HPn] [publisher ...]
/usr/bin/pkg history [-Hl] [-n number]
/usr/bin/pkg purge-history
/usr/bin/pkg rebuild-index
/usr/bin/pkg version
/usr/bin/pkg help
DESCRIPTION
pkg is the retrieval client for the image packaging system. With
a valid configuration, pkg can be invoked to create locations for
packages to be installed, called 'images', and install packages
into those images. Packages are published by publishers, who may
make their packages available at one or more repositories. pkg,
then, retrieves packages from a publisher's repository and
installs them into an image.
A publisher is a forward domain name that can be used to identify a
person, group of persons, or an organization as the source of one or
more packages. The name of a publisher does not have to be contained
within the URIs that identify the locations of publisher repositories.
For example, the name of a publisher might be "example.com", but its
repositories may be hosted at "example.org" or "example.net".
A repository is a location where clients can publish and retrieve
package content (files contained within the package such as programs,
documents, etc.) and metadata (information about the package such as
its name, description, etc.). As an example, a publisher named
"example.org" may have their repository located at the URI
"http://example.org/repository".
pkg can also uninstall packages, refresh publisher metadata (such as
catalogs), validate package installation in an image, and query the
image for various tokens. These queries can also be made of pkg(5)
repositories.
Images can be of three types: full images, capable of providing a
complete system; partial images, which are linked to a full image
(parent image), but do not provide a complete system on their own;
and user images, which contain only relocatable packages. (See
NOTES on user images.)
pkg(1) attempts to determine, based on its working directory, in
what image it has been invoked. If no image metadata can be found
in the parent directories, the invocation will fail.
OPTIONS
The following options are supported:
-R dir
Operate on the image rooted at dir, rather than the one discovered
automatically.
--help or -?
Displays a usage message.
SUBCOMMANDS
The following subcommands are supported:
image-create [-FPUfz] [--force] [--full|--partial|--user] [--zone]
[-k ssl_key] [-c ssl_cert] [--no-refresh]
[--variant <variant_spec>=<instance> ...]
[-g uri|--origin=uri ...] [-m uri|--mirror=uri ...]
[--facet <facet_spec>=[True|False] ...]
(-p|--publisher) [<name>=]<repo_uri> dir
Create, at location given by dir, an image suitable for package
operations. The default image type is user, as given by the -U
(--user) option. The image type may be set to a full image (-F
or --full) or to a partial image (-P or --partial) linked to the
full image enclosing the given dir path. Additional origins can
be specified using -g or --origin, while additional mirrors can
be specified using -m or --mirror.
A package repository URI must be provided using the -p or
--publisher option. If a publisher name is also provided, then
only that publisher will be added when the image is created. If
a publisher name is not provided, then all publishers known by the
specified repository will be added to the image. An attempt to
retrieve the catalog associated with this publisher will be made
following the initial creation operations.
For publishers using client SSL authentication, a client key and
client certificate may be registered via the -c and -k options,
and will be used for all publishers added during image creation.
If the image is to be run within nonglobal zone context, then
the -z (--zone) option can be used to set an appropriate filter.
With -f (--force), force the creation of an image over an existing
image. This option should be used with care.
With --no-refresh, do not attempt to contact the repositories for
the image's publishers to retrieve publisher metadata (e.g.
catalogs).
With --variant, set the specified variant to the indicated value.
With --facet, set the specified facet to the indicated value.
refresh [--full] [publisher ...]
Retrieve updates to the metadata (e.g. catalogs) for each publisher
specified. When given no arguments, retrieves updates for each
publisher registered within the image.
With --full, retrieve all publisher metadata instead of attempting an
incremental update.
install [-nvq] [--accept] [--licenses] [--no-index] [--no-refresh]
[--deny-new-be | --require-new-be] [--be-name] pkg_fmri_pattern ...
Installs and updates packages to the newest version that match
pkg_fmri_pattern allowed by the packages installed in the
image.
Some configuration files may be renamed or replaced during the
install process. For more information on how the package system
determines which files to preserve, and how they are preserved
during package operations, see "File Actions" in pkg(5).
With the -n option, execute the requested operation but make
no persistent changes to the image.
With the -v option, issue verbose progress messages during
the requested operation. With the -q option, issue no
progress messages during the requested operation.
With --accept, you indicate that you agree to and accept the
terms of the licenses of the packages that are updated or
installed. If you do not provide this option, and any
package licenses require acceptance, the operation will
fail.
With --licenses, display all of the licenses for the
packages that will be installed or updated as part of this
operation.
With --no-index, do not update the search indices after the
operation has completed successfully.
With --no-refresh, do not attempt to contact the
repositories for the image's publishers to retrieve
publisher metadata (e.g. catalogs).
With --be-name, rename the newly created boot environment to
be the argument given. This option is only valid if a new
boot environment is created during the operation. See also
beadm(1m).
With --require-new-be, always create a new boot environment.
Without this option, a boot environment is created
automatically if needed.
With --deny-new-be, disallow creation of a new boot
environment; the operation will not be performed if
a new boot environment is required.
uninstall [-nrvq] [--no-index] [--deny-new-be | --require-new-be]
[--be-name name] pkg_fmri_pattern ...
Removes installed packages that match pkg_fmri_pattern.
With -r, recursively uninstall any packages that contain
'require' dependencies on the initial package. (Packages
containing 'optional' or 'incorporate' dependencies are
not included in the removal.)
For all other options, refer to the install command above
for usage and their effects.
update [-fnvq] [--accept] [--be-name name] [--licenses]
[--no-index] [--no-refresh] [--deny-new-be | --require-new-be]
[pkg_fmri_pattern ...]
With no arguments, or if '*' is one of the patterns provided,
update all installed packages in the current image to the newest
version allowed by the constraints imposed on the system by
installed packages and publisher configuration.
If pkg_fmri_pattern is provided, update will replace packages
that are installed, and that match pkg_fmri_pattern, with the
newest version allowed by the pattern(s) and the constraints
imposed on the system by installed packages and publisher
configuration. Versions older or newer than what is already
installed may be specified to perform in place downgrades or
upgrades of specific packages. Please note that updating
specific packages across package rename or obsolete boundaries
is not supported.
Any preserved configuration files that are part of packages to
be downgraded by update and that have been changed since the
original version was installed will be renamed using the
extension '.update'. For more information on how the package
system determines which files to preserve, and how these files
are preserved during package upgrades, see "File Actions" in
pkg(5).
With the -f option, don't execute the client up to date check
when updating all installed packages.
For all other options, refer to the install command above for
usage and their effects.
info [-lr] [--license] [pkg_fmri_pattern ...]
Display information about packages in a human-readable form.
Multiple FMRI patterns may be specified; with no patterns,
display information on all installed packages in the image.
With -l, use the data available from locally installed packages.
This is the default.
With -r, retrieve the data from the repositories of the image's
configured publishers. Note that you must specify one or more
package patterns in this case.
With --license, print out the license text(s) for the package.
This may be combined with -l or -r.
contents [-Hmr] [-a attribute=pattern ...] [-o attribute ...]
[-s sort_key] [-t action_type ...] [pkg_fmri_pattern ...]
Display the contents (action attributes) of packages in the
current image. By default, only the path attribute is displayed,
but the attribute set may be determined with the -o option. The
-o option may be specified multiple times, or multiple attributes
may be specified as the argument to one -o option by separating
the attribute names with commas. Only actions which have the
requested attributes will be displayed. The -m option may
also be used, as a shorthand for '-Ho action.raw'.
The -a option allows you to limit the output to those actions
which have an attribute named in the option argument the value of
which matches the (glob) pattern in the option argument
(following the attribute name with an equals sign). If multiple
-a options are given, then actions matching any of them will be
displayed.
The -s option specifies the attribute by which the listing should
be sorted.
The -t option limits the action types which will be displayed.
The -H option causes the headers to be omitted.
The -r option retrieves the requested data from the repositories
of the image's configured publishers. This option is intended
to be used when the named packages are not already installed.
With no arguments, the output includes all installed packages.
Alternatively, multiple FMRI patterns may be specified, which
restricts the display to the contents of the matching packages.
When using -r, one or more pkg_fmri_patterns must be specified.
Several special "pseudo" attribute names are available for
convenience:
action.hash Corresponds to the value of the action's
hash, if the action carries a payload.
action.key Corresponds to the value of the action's
key attribute. For example, for a file
action, this is the path to the file.
action.name Corresponds to the name of the action.
For example, for a file action, this is
"file"
action.raw Corresponds to the complete contents of
the action as represented in the package
manifest. This corresponds to the
lines of output of 'pkg contents -m'
pkg.fmri Corresponds to the full form FMRI of the
package containing the action, such as
pkg://extra/virtualbox@3.0.0,5.11-0.101:20090702T175410Z
pkg.name Corresponds to the name of the package
containing the action, such as "SUNWcs"
pkg.publisher Corresponds to the publisher of the
the package containing the action, such
as "opensolaris.org"
pkg.shortfmri Corresponds to the short form FMRI of the
package containing the action, such as
pkg://opensolaris.org/SUNWzone@0.5.11-0.79
The contents and search subcommands are related: both are used to
query the system for the contents of packages. The contents
subcommand displays actions in one or more packages, filtering
the output based on the options chosen by the user. The search
subcommand approaches the query from the other direction, looking
for packages which contain a user-supplied token.
Each subcommand is capable of formulating some queries of which
the other is capable. Care should be taken in choosing the
subcommand, as a given query may be more naturally formulated in
one than in the other.
search [-HIaflpr] [-o attribute ...] [-s repo_uri] query
Search for matches to the query, and display the results.
Which tokens are indexed are action-dependent, but may
include content hashes and pathnames. By default, queries are
interpreted as a series of terms to be matched exactly. The
'?' and '*' characters can be used as glob(3C)-style
wildcards, allowing more flexible query matches.
With -H, omit the headers.
With -I, use a case-sensitive search.
By default, and with -a, perform the search and display information
about the matching actions.
By default, search prunes results from packages older than the
currently installed version and from package versions excluded by
current incorporations. Use -f to show all results, regardless of
package version.
With -l, search the image's installed packages.
With -o, the columns of the results may be controlled. The
-o option may be specified multiple times, or multiple attributes
may be specified as the argument to one -o option by separating
the attribute names with commas. In addition to the "pseudo"
attributes outlined above, more are defined for search results:
search.match Corresponds to the string which matched the
search query.
search.match_type Corresponds to the attribute which contained
the string that matched the search query.
With -p, display packages which have some actions that match each
query term. Using this option is equivalent to putting '<>' around
each term in the query. (For a description of the '<>' operator,
please see below.)
By default, and with -r, search the repositories corresponding
to the image's publishers.
With -s, search the pkg(5) repository located at the given URI.
This may be specified multiple times.
Both -l and -r (or -s) may be specified together, in which case both
local and remote searches will be performed.
In addition to simple token matching and wildcard search, a more
complicated query language is supported. Phrases may be searched for
by using ' or ". Note: Please make sure to take your shell into
account so that pkg actually sees the ' or ".
Boolean search using AND and OR is supported. Field, or structured,
queries are supported. The syntax for these is
pkg_name:action_type:key:token. Missing fields are implicitly
wildcarded. A search for :basename:pkg would match all actions
types in all packages with a key of basename and which matched
the token 'pkg'. Explicit wildcards are supported in the pkg_name
and token fields, action_type and key must match exactly.
To convert actions to the packages which contain those actions,
use '<>'. With the -a option, Searching for 'token' results in
information about the actions matching token, while searching for
'<token>' results in a list of packages containing actions which
matched token.
list [-Hafnsuv] [--no-refresh] [pkg_fmri_pattern ...]
Display a list of packages in the current image, including
state and other information. By default, package variants
for a different architecture or zone type are excluded.
The usual output is in four columns:
NAME (PUBLISHER) VERSION STATE UFOXI
SUNWcs 0.5.11-0.126 installed -----
web/firefox/plugin/flash (extra) 10.0.32.18-0.111 installed -----
The first column contains the name of the package. If the publisher
from which it is installed (or available, if not installed) is not
the preferred publisher, then the publisher name is listed in
parentheses after the package name. The second column contains the
release and branch versions of the package (see pkg(5)). The third
column contains the state of the package as it exists on the system.
Possible values are "installed" and "known". The last column
contains a set of flags that show how the package relates to other
packages:
- a "u" in the "U" column shows that a newer version is
available, although it may not be possible to install
this newer version due to package dependencies or
constraints;
- an "f" in the "F" column shows that this version has
been frozen (not implemented);
- an "o" in the "O" column shows that it is obsolete,
while an "r" shows that it has been renamed (a form of
obsoletion);
- an "x" in the "X" column shows that it is prevented from
being installed because some other package has excluded
it (not implemented); and
- an "i" in the "I" column shows that it has been
constrained by an incorporation (not implemented).
With -H, omit the headers from the listing.
With -a, list installed packages and the newest version of
packages that are available for installation. Packages are
considered to be available for installation if they are
allowed by the installed incorporations and by the image's
variants. If one or more patterns are specified, then the
newest version matching the specified pattern and is also
allowed by any installed incorporations and the image's
variants will be listed. Without -a, list only installed
packages.
With -f and -a, list all versions of all packages for all
variants regardless of incorporation constraints or installed
state.
With -n, display the newest versions of all known packages,
regardless of installed state.
With -s, display a one-line short-form giving the package name
and description. This option may be used with -a, -n, -u or
-v.
With -u, list only packages with newer versions available.
With -v, show full package FMRIs, including publisher and
complete version, all in the first column (the VERSION column
disappears). This option may be used with -a, -n, or -u.
With --no-refresh, do not attempt to contact the repositories
for the image's publishers to retrieve publisher metadata (e.g.
catalogs).
verify [-Hqv] [pkg_fmri_pattern ...]
Validate the installation of packages in the current image.
Please note that verification of installed package content is
based on a custom content analysis that may return different
results than those of other programs.
With -H, omit the headers from the verification output.
With -q, print nothing, but return failure if there are any
fatal errors.
With -v, include informational messages regarding packages.
variant [-H] [<variant_spec> ...]
Display the current values of all variants, or with arguments,
only the variants specified
With -H, omit the headers from the listing.
change-variant [-nvq] [--accept] [--be-name name] [--licenses]
<variant_spec>=<instance> ...
Change the specified variants in the current image.
With the -n option, plan the requested operation but make
no actual changes.
With the -v option, issue verbose progress messages during the
requested operation. With the -q option, be completely silent.
With --accept, you indicate that you agree to and accept the
terms of the licenses of the packages that are updated or
installed. If you do not provide this option, and any package
licenses require acceptance, the operation will fail.
With --licenses, display all of the licenses for the packages that
will be installed or updated as part of this operation.
With --be-name, rename the newly created boot environment to be the
argument given. This option is only valid if a new boot environment
is created during image update. See also beadm(1m).
With --require-new-be, always create a new boot environment. Without
this option, a new boot environment is only created if needed.
With --deny-new-be, disallow creation of a new boot environment;
the operation will not be performed if a new boot environment is
required.
facet [-H] [<facet_spec> ...]
Without arguments, displays the current values of all facets. With
argument(s), evaluate if each facet would be true or false and print
the result.
With -H, omit the headers from the listing.
change-facet [-nvq] [--accept] [--be-name name] [--licenses]
<facet_spec>=[True|False|None] ...
Change the specified facets in the current image.
With the -n option, plan the requested operation but make
no actual changes.
With the -v option, issue verbose progress messages during the
requested operation. With the -q option, be completely silent.
With --accept, you indicate that you agree to and accept the
terms of the licenses of the packages that are updated or
installed. If you do not provide this option, and any package
licenses require acceptance, the operation will fail.
With --licenses, display all of the licenses for the packages that
will be installed or updated as part of this operation.
With --be-name, rename the newly created boot environment to be the
argument given. This option is only valid if a new boot environment
is created during the operation. See also beadm(1m).
With --require-new-be, always create a new boot environment. Without
this option, a new boot environment is only created if needed.
With --deny-new-be, disallow creation of a new boot environment;
the operation will not be performed if a new boot environment is
required.
Facets may be set to True or False. Setting one to None removes
that facet specification from the current image.
fix [--accept] [--licenses] [pkg_fmri_pattern ...]
Fix any errors reported by pkg verify. Please note that
verification of installed package content is based on a
custom content analysis that may return different results
than those of other programs.
With --accept, you indicate that you agree to and accept the
terms of the licenses of the packages that are updated or
installed. If you do not provide this option, and any package
licenses require acceptance, the operation will fail.
With --licenses, display all of the licenses for the packages that
will be installed or updated as part of this operation.
set-property propname propvalue
Update an existing image property or add a new image property;
except for preferred-publisher, which can only be changed using
set-publisher.
add-property-value propname propvalue
Add a value to an existing image property or add a new image property;
except for preferred-publisher, which can only be changed using
set-publisher.
remove-property-value propname propvalue
Remove a value from an existing image property; except for
preferred-publisher, which can only be changed using set-publisher.
unset-property propname ...
Remove an existing image property or properties; except for
preferred-publisher, which can only be changed using
set-publisher.
property [-H] [propname ...]
Display image property information. With no argument, display the
names and values for all image properties. If a specific list of
property names is requested, display the names and values for those
properties.
With -H, omit the headers from the listing.
set-publisher [-Ped] [-k ssl_key] [-c ssl_cert]
[-g origin_to_add|--add-origin=origin_to_add ...]
[-G origin_to_remove|--remove-origin=origin_to_remove ...]
[-m mirror_to_add|--add-mirror=mirror_to_add]
[-M mirror_to_remove|--remove-mirror=mirror_to_remove]
[-p repo_uri] [--enable] [--disable] [--no-refresh]
[--reset-uuid] [--non-sticky] [--sticky]
[--search-after=publisher] [--search-before=publisher]
[--approve-ca-cert path_to_CA]
[--revoke-ca-cert hash_of_CA_to_remove]
[--unset-ca-cert hash_of_CA_to_remove]
[--set-property name_of_property=value]
[--add-property-value name_of_property=value_to_add]
[--remove-property-value name_of_property=value_to_remove]
[--unset-property name_of_property_to_delete]
[publisher]
Update an existing publisher or add an additional package
publisher. If no options affecting search order are specified,
new publishers are appended to the search order and are thus
searched last.
With -P, set the specified publisher as the preferred
publisher, i.e. first in the search order. When installing
new packages, this publisher will be searched first.
Updates to already installed packages will come from the
same publisher that originally provided the package so long
as that publisher remains sticky.
With --non-sticky, specify that higher ranked publishers than
this one may provide updates to packages originally installed
from this publisher.
With --sticky, return to the default behavior of always sourcing
updates from the same publisher that provided the package originally.
With --search-before, alter the publisher search order so that
the publisher being modified is now searched before the specified
publisher.
With --search-after, alter the publisher search order so that
the publisher being modified is now searched after the specified
publisher.
With --approve-ca-cert, add the given certificate as a CA certificate
that is trusted. The hashes of the user approved CA certificates are
listed in the output of the detailed pkg publisher view for a
publisher.
With --revoked-ca-cert, treat the certificate with the given hash as
revoked. The hashes of the user revoked CA certificates are
listed in the output of the detailed pkg publisher view for a
publisher.
With --unset-ca-cert, remove the certificate with the given hash from
the list of approved and the list of revoked certificates.
With --set-property, update an existing publisher property or add a
new publisher property.
With --add-property-value, add a value to an existing publisher
property or add a new publisher property.
With --remove-property-value, remove a value from an existing
publisher property.
With --unset-property, remove an existing publisher property.
With -c and -k, specify client SSL certificate and key respectively.
With -g (--add-origin), add the URI as an origin for the given
publisher. This should be the location of a package repository.
With -G (--remove-origin), remove the URI from the list of origins
for the given publisher.
With --no-refresh, do not attempt to contact the publisher
specified to retrieve its metadata (e.g. catalog).
With --reset-uuid, choose a new unique identifier that identifies
this image to its publisher.
With -m (--add-mirror), add the URI as a mirror for the given
publisher.
With -M (--remove-mirror), remove the URI from the list of mirrors
for the given publisher.
With -p, retrieve publisher configuration information from the
specified repository URI. If a publisher is specified, then only
the matching one will be added or updated. If no publisher is
specified, all will be added or updated as appropriate. This option
may not be combined with the -g, --add-origin, -G, --remove-origin,
-m, --add-mirror, -M, --remove--mirror, --disable, --enable,
--no-refresh, or --reset-uuid options.
With -e (--enable), enable the publisher; with -d (--disable), disable
the publisher. A disabled publisher is not used when populating the
package list or in certain package operations (install, uninstall, and
update). However, the properties for a disabled publisher can still
be set and viewed. If only one publisher exists, it cannot be
disabled.
unset-publisher publisher ...
Remove the configuration associated with the given publisher
or publishers.
publisher [-HPn] [publisher ...]
Display publisher information. With no arguments, display
the list of all publishers, their origin URIs, and mirrors
in order of search preference. If specific publishers are
requested, display the configuration values, including
mirrors, associated with those publishers.
With -H, omit the headers from the listing.
With -P, display only the preferred publisher.
With -n, display only enabled publishers.
history [-Hl] [-n number]
Display the command history of the applicable image.
With -H, omit the headers from the listing.
With -l, display log records in long format, which, in addition to
the standard format, includes the outcome of the command, the time
the command completed, the version and name of the client used, the
name of the user who performed the operation, and any errors that
were encountered while executing the command.
With -n, display only the specified number of most recent entries.
purge-history
Deletes all existing history information.
rebuild-index
Rebuilds the index used by 'pkg search'. This is a recovery operation
not intended for general use.
version
Display a unique string identifying the version of pkg(1). This
string is not guaranteed to be comparable in any fashion between
versions.
IMAGE PROPERTIES
The following properties are part of the image and may be set using
the set-property subcommand. The values of these properties are
viewable with the property subcommand.
ca-path
(string) A pathname that points to a directory where CA certs are
kept for SSL operations. The format of this directory is specific
to the underlying SSL implementation. If the administrator
would like to use an alternate location for trusted CA
certificates, this value should be changed to point to a
different directory. Please see the 'CApath' portions of
SSL_CTX_load_verify_locations(3openssl) for requirements
about the CA directory.
Default value: /etc/openssl/certs
flush-content-cache-on-success
(boolean) If this is set to True, the package client will remove
the files in its content-cache when install or update operations
complete. For update operations, the content is removed only
from the source BE. When a packaging operation next occurs in
the destination BE, it will flush its content cache, provided
this option has not been changed.
This property may be used to keep the content-cache small on
systems with limited disk space, but it may cause operations
to take longer to complete.
Default value: False
mirror-discovery
(boolean) Mirror-discovery tells the client to discover
link-local content mirrors using mDNS and DNS-SD. If this is
set to True, the client will attempt to download package content
from mirrors it dynamically discovers. To run a mirror that
advertises its content via mDNS, see pkg.depotd(1m).
Default value: False
send-uuid
(boolean) Send the image's Universally Unique Identifier
(UUID) when performing network operations. Although users may
disable this option, some network repositories may refuse to talk
to clients that do not supply a UUID.
Default value: True
signature-policy
(string) Determine what checks will be performed on manifests
when installing a package into this image. The final policy
applied to a package depends on the combination of image policy
and publisher policy. The combination will be at least as strict
as the stricter of the two policies taken individually. The
following are the valid values for this property.
ignore
Ignore signatures for all manifests.
verify
Verify that all manifests with signatures are validly
signed, but do not require all installed packages to be
signed.
require-signatures
Require that all newly installed packages have at least
one valid signature. 'pkg fix' and 'pkg verify' will also
warn if an installed package does not have a valid
signature.
require-names
Follow the same requirements as 'require-signatures' but
also require that the strings listed in the
'signature-required-names' property appear as a common
name of the certificates used to verifiy the chains
of trust of the signatures.
signature-required-names
(list of strings) A list of names which must be seen as common
names of certificates while validating the signatures of a
package.
trust-anchor-directory
(string) The pathname of the directory that contains the trust
anchors for the image. This path is relative to the image.
PUBLISHER PROPERTIES
The following properties are part of the image and may be set using
the set-property option of the set-publisher subcommand.
signature-policy
(string) This property functions identically to the image
property of the same name except it only applies to packages
from the particular publisher.
signature-required-names
(list of strings) This property functions identically to the
image property of the same name except it only applies to
packages from the particular publisher.
EXAMPLES
Example 1: Create a new, full image, with publisher example.com,
stored at /aux0/example_root.
$ pkg image-create -F -p example.com=http://pkg.example.com:10000 \
/aux0/example_root
Example 2: Create a new, full image, with publisher example.com,
that also has an additional mirror, two additional origins and is
stored at /aux0/example_root.
$ pkg image-create -F -p example.com=http://pkg.example.com:10000 \
-g http://alternate1.example.com:10000/ \
-g http://alternate2.example.com:10000/ \
-m http://mirror.example.com:10000/ \
/aux0/example_root
Example 3: Install the latest version of the widget package in the
current image.
$ pkg install application/widget
Example 4: List the contents of the SUNWzfs package. Display the
action name, the mode of the file (if defined), the size (if defined),
the path, and the target (if a link). Limit the action to types dir,
file, link, and hardlink, since specifying the action.name attribute,
which is available for all actions, will display a line for all
actions, which is not desired here.
$ pkg contents -t dir,file,link,hardlink \
-o action.name,mode,pkg.size,path,target SUNWzfs
NAME MODE SIZE PATH TARGET
dir 0755 etc
dir 0755 etc/fs
dir 0755 etc/fs/zfs
link etc/fs/zfs/mount ../../../sbin/zfs
link etc/fs/zfs/umount ../../../sbin/zfs
dir 0755 etc/zfs
dir 0755 lib
dir 0755 lib/amd64
link lib/amd64/libzfs.so libzfs.so.1
file 0755 469616 lib/amd64/libzfs.so.1
file 0644 62057 lib/amd64/llib-lzfs.ln
link lib/libzfs.so libzfs.so.1
....
Example 5: List the contents of SUNWfirefox and SUNWthunderbird,
limiting the display to just the package name and path attributes of
actions whose "path" attribute ends in ".desktop" or ".png".
$ pkg contents contents -o pkg.name,path -a path=\*.desktop \
-a path=\*.png SUNWfirefox SUNWthunderbird
PKG.NAME PATH
SUNWfirefox usr/lib/firefox/chrome/icons/default/default16.png
SUNWfirefox usr/lib/firefox/chrome/icons/default/default32.png
SUNWfirefox usr/lib/firefox/chrome/icons/default/default48.png
SUNWfirefox usr/lib/firefox/icons/document.png
SUNWfirefox usr/lib/firefox/icons/mozicon128.png
SUNWfirefox usr/lib/firefox/res/html/folder.png
SUNWfirefox usr/share/applications/firefox.desktop
SUNWthunderbird usr/share/applications/thunderbird.desktop
SUNWfirefox usr/share/pixmaps/firefox-icon.png
SUNWthunderbird usr/share/pixmaps/thunderbird-icon.png
Example 6: Search the package database for the token "bge".
$ pkg search bge
INDEX ACTION VALUE PACKAGE
basename file kernel/drv/bge pkg:/SUNWbge@0.5.11-0.79
driver_name driver bge pkg:/SUNWbge@0.5.11-0.79
The token shows up in the package SUNWbge both as the basename for the
file action representing /kernel/drv/bge and as a driver name.
Example 7: Search for installed packages which depend on SUNWipkg.
$ pkg search -l 'depend::SUNWipkg'
INDEX ACTION VALUE PACKAGE
incorporate depend SUNWipkg@0.5.11-0.111 pkg:/entire@0.5.11-0.111
require depend SUNWipkg@0.5.11-0.111 pkg:/slim_install@0.1-0.111
require depend SUNWipkg@0.5.11-0.111 pkg:/SUNWipkg-brand@0.5.11-0.111
Example 8: Search for all incorporate dependencies in installed packages.
$ pkg search -l 'depend:incorporate:'
INDEX ACTION VALUE PACKAGE
incorporate depend BRCMbnx@0.5.11-0.111 pkg:/entire@0.5.11-0.111
incorporate depend BRCMbnx@0.5.11-0.111 pkg:/entire@0.5.11-0.111
....
Example 9: Add new publisher example.org, with a repository located at
http://www.example.org/repo:
$ pkg set-publisher -g http://www.example.org/repo example.org
Example 10: Add new publisher example.com, with a secure repository
located at https://secure.example.com/repo, and a key and cert stored
in the directory /root/creds:
$ pkg set-publisher -k /root/creds/example.key \
-c /root/creds/example.cert -g https://secure.example.com/repo \
example.com
Example 11: Add new publisher with a repository located at
/export/repo using automatic configuration:
$ pkg set-publisher -p file:/export/repo
Example 12: Add new publisher example.org with a repository located
at /export/repo/example.com using manual configuration:
$ pkg set-publisher -g file:/export/repo example.com
Example 13: Configure an image to verify all signed packages.
$ pkg set-property signature-policy verify
Example 14: Configure an image to require all packages to be signed and
the string "opensolaris.org" has to be seen as a common name for one of
the certificates in the chain of trust.
$ pkg set-property signature-policy require-names opensolaris.org
Example 15: Configure an image so that all packages installed from
publisher foo must be signed.
$ pkg set-publisher --set-property signature-policy=require-signatures
Example 16: Add the string "foo" to the image's list of common names that
must be seen in a signature's chain of trust to be considered valid.
$ pkg add-property-value signature-require-names foo
Example 17: Remove the string "foo" from publisher test's list of common
names that must be seen to validate a signature.
$ pkg set-publisher --remove-property-value signature-require-names=foo \
test
Example 18: Add the certificate stored in /tmp/example_file.pem as a
trusted CA certificate for the publisher test.
$ pkg set-publisher --approve-ca-cert /tmp/example_file.pem
Example 19: Revoke the certificate with the hash a12345 for publisher
test, preventing it from validating any signatures for packages from test.
$ pkg set-publisher --revoke-ca-cert a12345
Example 20: Make pkg forget that the certificate a12345 was ever added or
revoked by the user.
$ pkg set-publisher --unset-ca-cert a12345
Example 21: Downgrade the installed package foo@1.1 to an older
version:
$ pkg update foo@1.0
EXIT STATUS
The following exit values are returned:
0 Command succeeded.
1 An error occurred.
2 Invalid command line options were specified.
3 Multiple operations were requested, but only some of them
succeeded.
4 No changes were made - nothing to do.
5 The requested operation cannot be performed on a live
image.
6 The requested operation cannot be completed as the licenses
for the packages being installed or updated have not been
accepted.
7 The image is currently in use by another process and cannot
be modified.
FILES
A pkg(5) image can be located arbitrarily within a larger file
system. In the following, the token $IMAGE_ROOT is used to
distinguish relative paths. For a typical system installation,
$IMAGE_ROOT is equivalent to "/".
$IMAGE_ROOT/var/pkg Metadata directory for a full or partial
image.
$IMAGE_ROOT/.org.opensolaris,pkg
Metadata directory for a user image.
Within a particular image's metadata, certain files and directories
can contain information useful during repair and recovery. We use
the token $IMAGE_META to refer to the top-level directory
containing the metadata. $IMAGE_META is typically one of the two
paths given above.
$IMAGE_META/lost+found Location of conflicting directories and
files moved during a package operation.
$IMAGE_META/publisher Contains a directory for each publisher.
Each directory stores publisher-specific
metadata.
Other paths within the $IMAGE_META directory hierarchy are Private,
and are subject to change.
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | SUNWipkg |
| | pkg:/package/pkg |
|_____________________________|_____________________________|
| Interface Stability | None / Under Development |
|_____________________________|_____________________________|
SEE ALSO
pkgsend(1), pkg.depotd(1M), glob(3C), attributes(5), pkg(5)
NOTES
The image packaging system is an under-development feature.
Command names, invocation, formats, and operations are all subject
to change. Development is hosted in the OpenSolaris community
at:
http://hub.opensolaris.org/bin/view/Project+pkg/
At present, user images are not restricted to relocatable
packages--but they will be.
The pkg(1) command recognizes use of the http_proxy and https_proxy
environment variables to select a suitable HTTP or HTTPS proxy
server. At present, particular care is needed when using local
repository URIs--such as http://localhost:10000/--with the
http_proxy environment variable; this behavior may change in a
future version of image packaging.
At present, pkg(1), on directory removal, will move unpackaged
contents of that directory to $IMAGE_META/lost+found.
