User Commands pkg(1) NAME pkg - image packaging retrieval client SYNOPSIS /usr/bin/pkg [options] command [cmd_options] [operands] /usr/bin/pkg install [-nvq] pkg_fmri ... /usr/bin/pkg uninstall [-nrvq] pkg_fmri ... /usr/bin/pkg verify [-fHvq] [pkg_fmri_pattern ...] /usr/bin/pkg info [-lr] [--license] [pkg_fmri_pattern ...] /usr/bin/pkg contents [-Hmr] [-o attribute ...] [-s sort_key] [-t action_type ... ] [pkg_fmri_pattern ...] /usr/bin/pkg list [-aHsuv] [pkg_fmri_pattern ...] /usr/bin/pkg search [-lr] [-s server] token /usr/bin/pkg refresh [--full] /usr/bin/pkg image-create [-FPUz] [--full|--partial|--user] [--zone] [-k ssl_key] [-c ssl_cert] -a authority=origin_url dir /usr/bin/pkg image-update [-nvq] /usr/bin/pkg set-authority [-P] [-k ssl_key] [-c ssl_cert] [-O origin_url] authority /usr/bin/pkg unset-authority authority ... /usr/bin/pkg authority [-HP] [authname ...] /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 images, target locations for packages to be installed, and install packages into those images. pkg can also uninstall packages, refresh the package catalogs, validate package installation in an image and query the image for various tokens 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 option is supported: -R dir Operate on the image rooted at dir, rather than the one discovered automatically. SUBCOMMANDS The following subcommands are supported: image-create [-FPUz] [--full|--partial|--user] [--zone] [-k ssl_key] [-c ssl_cert] -a authority=origin_url 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 authority must be set using the -a option. An attempt to retrieve the catalog associated with this authority will be made following the initial creation operations. For authorities using client SSL 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. image-update [-nvq] Update all installed packages in the current image to the latest available version. 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. refresh [--full] Retrieve updates to the catalogs for each authority registered within the image. With --full, retrieve the full catalogs. install [-nvq] pkg_fmri ... uninstall [-nrvq] pkg_fmri ... Install or remove the package specified by pkg_fmri or matching pkg_fmri 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. In the case of uninstall, the -r option will recursively uninstall any packages which are dependent on the initial package. 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 servers. 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 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 '-o 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 server, for use in cases when the package is 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.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.authority Corresponds to the authority of the the package containing the action, such as "opensolaris.org" search [-lr] [-s server] token Search for the token "token", and display the FMRIs in which the token was found. Which tokens are indexed are action-dependent, but may include content hashes and pathnames. By default, and with -l, search the image's installed packages. With -r, search the servers corresponding to the image's authorities. With -s, search the named servers. 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. list [-aHsuv] [pkg_fmri_pattern ...] Report on the state of packages in the current image. With -a, report on all packages known, whether installed or not; without -a, report only based on installed packages in the image. 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. verify [-fHqv] [pkg_fmri_pattern ...] 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. With -f, fully validate the contents of files against the hash values in the package manifests, as well as checking for file and directory presence. The -H option causes the headers to be omitted. set-authority [-P] [-k ssl_key] [-c ssl_cert] [-O origin_url] authority Update an existing authority or add an additional package authority. With -P, set the specified authority as the preferred authority. With -c and -k, specify client SSL certificate and key respectively. The -O option sets the URL prefix for the origin packaging repository for the authority. unset-authority authority ... Remove the configuration associated with the given authority or authorities. authority [-HP] [authname] Display authority information. With no arguments, display the list of configured authorities, and their origin URLs. If a specific authority is requested, display the configuration values associated with that authority. With -H, omit the headers from the listing. With -P, display only the preferred authority. 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. help Display a usage message. EXAMPLES Example 1: Create a new, full image, with authority example.com, stored at /aux0/example_root $ pkg image-create -F -a example.com=http://pkg.example.com:10000 \ /aux0/example_root 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 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. EXIT STATUS The following exit values are returned: 0 Everything worked. 1 Something bad happened. 2 Invalid command line options were specified. 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 authorities. ATTRIBUTES See attributes(5) for descriptions of the following attri- butes: ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Availability | | | 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. Although HTTPS servers may validate client SSL certificates, the client does not currently validate the server's.