User Commands pkg(1)
NAME
pkg - image packaging retrieval client
SYNOPSIS
/usr/bin/pkg [options] command [cmdoptions] [operands]
/usr/bin/pkg install [-nvq] [--no-refresh] [--no-index] pkgfmri ...
/usr/bin/pkg uninstall [-nrvq] [--no-index] pkgfmri ...
/usr/bin/pkg verify [-Hvq] [pkgfmripattern ...]
/usr/bin/pkg fix [pkgfmripattern ...]
/usr/bin/pkg info [-lr] [--license] [pkgfmripattern ...]
/usr/bin/pkg contents [-Hmr] [-o attribute ...] [-s sortkey]
[-t actiontype ... ] [pkgfmripattern ...]
/usr/bin/pkg list [-Hafsuv] [--no-refresh] [pkgfmripattern ...]
/usr/bin/pkg search [-alprI] [-s repouri] query
/usr/bin/pkg refresh [--full] [publisher ...]
/usr/bin/pkg image-create [-fFPUz] [--force] [--full--partial--user]
[--zone] [-k sslkey] [-c sslcert] [--no-refresh]
(-p--publisher) name=uri dir
/usr/bin/pkg image-update [-fnvq] [--be-name name] [--no-refresh]
[--no-index]
/usr/bin/pkg set-property propname propvalue
/usr/bin/pkg unset-property propname ...
/usr/bin/pkg property [-H] [propname ...]
/usr/bin/pkg set-publisher [-Ped] [-k sslkey] [-c sslcert]
[-O originuri] [-m mirrortoadd --add-mirror=mirrortoadd]
[-M mirrortoremove --remove-mirror=mirrortoremove]
[--enable] [--disable] [--no-refresh] [--reset-uuid] publisher
/usr/bin/pkg unset-publisher publisher ...
/usr/bin/pkg publisher [-HPa] [publisher ...]
/usr/bin/pkg history [-Hl]
/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.
pkg can also uninstall packages, refresh the package 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.
SUBCOMANDS
The following subcommands are supported:
image-create [-fFPUz] [--force] [--full--partial--user] [--zone]
[-k sslkey] [-c sslcert] [--no-refresh]
(-p--publisher) name=originuri 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.
A preferred publisher must be provided using the -p or --publisher
option. An attempt to retrieve the catalog associated with this
publisher will be made following the initial creation operations.
For publishers using client SL authentication, a client key and
client certificate may be registered via the -c and -k options.
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).
image-update [-fnvq] [--be-name name] [--no-index] [--no-refresh]
Update all installed packages in the current image to the
latest available version.
With the -f option, skip safety checks.
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, be completely silent.
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 --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).
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] [--no-index] [--no-refresh] pkgfmri ...
uninstall [-nrvq] [--no-index] pkgfmri ...
Install or remove the package specified by pkgfmri or
matching pkgfmri as a substring. 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.
In the case of uninstall, the -r option will recursively
uninstall any packages which are dependent on the initial
package.
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).
info [-lr] [--license] [pkgfmripattern ...]
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] [-o attribute ...] [-s sortkey] [-t actiontype ... ]
[pkgfmripattern ...]
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 -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 pkgfmripatterns must be specified.
Several special "pseudo" attribute names are available for
convenience:
action.name Corresponds to the name of the action.
For example, for a file action, this is
"file"
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.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.name Corresponds to the name of the package
containing the action, such as "SUNWcs"
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
pkg.publisher Corresponds to the publisher of the
the package containing the action, such
as "opensolaris.org"
search [-alprI] [-s repouri] 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, and with -a, perform the search and display information
about the matching actions.
With -l, search the image's installed packages.
With -p, perform the search and display the packages which contain
at least one action which matched the query. This is equivalent to
enclosing the entire query with '<>'. (For a description of the
'<>' operator, please see below.)
By default, and with -r, search the repositories corresponding
to the image's publishers.
With -I, use a case-sensitive search.
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
pkgname:actiontype:key:token. Missing fields are implictly
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'. Explict wildcards are supported in the pkgname and
token fields, actiontype 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
'' results in a list of packages containing actions which
matched token.
list [-Hafsuv] [--no-refresh] [pkgfmripattern ...]
Display a list of packages in the current image, including state
and other information.
With -H, omit the headers from the listing.
With -a, report on all packages known, whether installed or not;
without -a, report only based on installed packages in the
image.
With -f, report all versions of packages; without -f report only the
installed and newest version of a package.
With -s, display a one-line short-form giving the package name and
description.
With -u, report only packages with newer versions available.
With -v, report full package FMRIs.
With --no-refresh, do not attempt to contact the repositories for
the image's publishers to retrieve publisher metadata (e.g.
catalogs).
verify [-Hqv] [pkgfmripattern ...]
Validate the installation of packages in the current image.
With -v, do more verbose reporting. With -q, print nothing, but
return failure if there are any verification problems. File hashes
are always checked.
The -H option causes the headers to be omitted.
fix [pkgfmripattern ...]
Fix any errors reported by pkg verify.
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.
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 sslkey] [-c sslcert] [-O originuri]
[-m mirrortoadd --add-mirror=mirrortoadd]
[-M mirrortoremove --remove-mirror=mirrortoremove]
[--enable] [--disable] [--no-refresh] [--reset-uuid] publisher
Update an existing publisher or add an additional package
publisher.
With -P, set the specified publisher as the preferred publisher.
With -c and -k, specify client SL certificate and key respectively.
With -O, set the origin URI for the publisher packaging repository.
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 -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
image-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 [-HPa] [publisher ...]
Display publisher information. With no arguments, display the
list of enabled publishers, their origin URIs, and mirrors. 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 -a, display all publishers (including those
that are disabled).
history [-Hl]
Displays 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, when the command completed, version and name of the
client used, what user performed the operation, and any errors that
were encountered while executing the command.
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.
EXAMPLES
Example 1: Create a new, full image, with publisher example.com,
stored at /aux0/exampleroot
$ pkg image-create -F -a example.com=http:/pkg.example.com:10000 \
/aux0/exampleroot
Example 2: Install the latest version of the widget package in the
current image.
$ pkg install application/widget
Example 3: 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 4: 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
drivername 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.
EXIT STATUS
The following exit values are returned:
0 Everything worked.
1 Something bad happened.
2 Invalid command line options were specified.
3 Multiple operations were requested, but only some of them
succeeded.
FILES
var/pkg Metadata location for full and partial
images, relative to image's root
directory.
.org.opensolaris,pkg Metadata location for user images,
relative to image's root directory.
Metadata is stored in an equivalent tree and format for any image
type, starting at $META as above.
$META/catalog Directory of catalogs from defined
publishers.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWipkg
Interface Stability None / Under Development
SEE ALSO
pkgsend(1), pkg.depotd(1M), 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:/opensolaris.org/os/project/pkg/
At present, user images are not restricted to relocatable
packages--but they will be.
The pkg(1) command recognizes use of the httpproxy environment
variable to select a suitable HTP proxy server. At present,
particular care is needed when using local repository URIs--such as
http:/localhost:10000/--with the httpproxy environment variable;
this behaviour may change in a future version of image packaging.
Although HTPS servers may validate client SL certificates, the
client does not currently validate the server's.
|
