User Commands                                            pkg(1)

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] pkg_fmri_pattern ...

     /usr/bin/pkg uninstall [-nrvq] [--no-index] pkg_fmri_pattern ...

     /usr/bin/pkg image-update [-fnvq] [--accept] [--be-name name]

         [--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] [--be-name name]

         [--licenses] <variant_spec>=<instance> ...

     /usr/bin/pkg facet [-H] [<facet_spec>]

     /usr/bin/pkg change-facet [-nvq] [--accept] [--be-name name]

         [--licenses] <facet_spec>=[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 ...]

         [-p repo_uri] [--enable] [--disable] [--no-refresh]

         [--reset-uuid] [--non-sticky] [--sticky]

         [--search-after=publisher] [--search-before=publisher]

         [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.

     image-update [-fnvq] [--accept] [--be-name name] [--licenses]

       [--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 --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 --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 --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).

     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]

       pkg_fmri_pattern ...

     uninstall [-nrvq] [--no-index] pkg_fmri_pattern ...

          Install or remove the package specified by pkg_fmri_pattern or

          matching it 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 that contain 'require' dependencies on

          the initial package.  (Packages containing 'optional' or

          'incorporate' dependencies are not included in the removal.)

          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).

     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/[email protected],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/[email protected]

          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.