User Commands pkg(1) NAME pkg - image packaging retrieval client SYNOPSIS /usr/bin/pkg [options] command [cmd_options] [operands] /usr/bin/pkg install [-nvq] [--no-refresh] [--no-index] pkg_fmri ... /usr/bin/pkg uninstall [-nrvq] [--no-index] pkg_fmri ... /usr/bin/pkg verify [-Hvq] [pkg_fmri_pattern ...] /usr/bin/pkg fix [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 [-Hafsuv] [--no-refresh] [pkg_fmri_pattern ...] /usr/bin/pkg search [-alprHI] [-o attribute ...] [-s repo_uri] query /usr/bin/pkg refresh [--full] [publisher ...] /usr/bin/pkg image-create [-fFPUz] [--force] [--full|--partial|--user] [--zone] [-k ssl_key] [-c ssl_cert] [--no-refresh] [--variant =] [-g|--origin ...] [-m|--mirror ...] [--facet =[True|False]] (-p|--publisher) name=uri dir /usr/bin/pkg image-update [-fnvq] [--be-name name] [--no-refresh] [--no-index] /usr/bin/pkg variant [] /usr/bin/pkg change-variant [-nvq] [--be-name name] = ... /usr/bin/pkg facet [] /usr/bin/pkg change-facet [-nvq] [--be-name name] =[True|False|None] ... /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 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 ...] [--search-before publisher] [--search-after publisher] [--sticky] [--non-sticky] [--enable] [--disable] [--no-refresh] [--reset-uuid] publisher /usr/bin/pkg unset-publisher publisher ... /usr/bin/pkg publisher [-HPn] [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. 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 [-fFPUz] [--force] [--full|--partial|--user] [--zone] [-k ssl_key] [-c ssl_cert] [--no-refresh] [-g|--origin ...] [--variant =] ... [--facet =[True|False]] ... [-m|--mirror ...] (-p|--publisher) name=origin_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 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 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. 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. 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] pkg_fmri ... uninstall [-nrvq] [--no-index] 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. 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] [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] [-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 -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.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 [-alprHI] [-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, and with -a, perform the search and display information about the matching actions. 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, 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 -H, omit the headers. 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 pkg_name:action_type: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 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 '' results in a list of packages containing actions which matched token. list [-Hafsuv] [--no-refresh] [pkg_fmri_pattern ...] Display a list of packages in the current image, including state and other information. 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 it can be upgraded; - 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, 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, including publisher and complete version, all in the first column (the VERSION column disappears). 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. 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. variant [ ...] Display the current values of all variants, or with arguments, only the variants specified change-variant [-nvq] [--be-name name] = [= ...] 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 --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). facet [ ...] Without arguments, displays the current values of all facets. With argument(s), evalute if each facet would be true or false and print the result. change-facet [-nvq] [--be-name name] =[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 --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). Facets may be set to True or False. Setting one to None removes that facet specification from the current image. fix [pkg_fmri_pattern ...] 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 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] [--search-before publisher] [--search-after publisher] [--sticky] [--non-sticky] [--enable] [--disable] [--no-refresh] [--reset-uuid] 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 -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 -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 [-HPn] [publisher ...] Display publisher information. With no arguments, display the list of all publishers, their origin URIs, and mirrors in search order 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] 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/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: 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 6: 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 7: 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 incorporate depend FSWxorg-fonts@0.5.11-0.111 pkg:/entire@0.5.11-0.111 incorporate depend FSWxorg-fonts-core@0.5.11-0.111 pkg:/entire@0.5.11-0.111 [ ... ] Example 8: 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 9: 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 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. 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. ATTRIBUTES See attributes(5) for descriptions of the following attri- butes: ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE 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 http_proxy environment variable to select a suitable HTTP 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 behaviour may change in a future version of image packaging. Although HTTPS servers may validate client SSL certificates, the client does not currently validate the server's.