'\" te

.\" Copyright (c) 2007, 2011, Oracle and/or its

.\" affiliates. All rights reserved.

.TH pkg 1 "28 Jul 2011" "" ""

.SH NAME

pkg \- Image Packaging System retrieval client

.SH SYNOPSIS

.LP

.nf

/usr/bin/pkg [\fIoptions\fR] command [\fIcmd_options\fR] [\fIoperands\fR]

.fi

.LP

.nf

/usr/bin/pkg refresh [--full] [\fIpublisher\fR ...]

.fi

.LP

.nf

/usr/bin/pkg install [-nvq] [-g \fIpath_or_uri\fR ...] [--accept]

    [--licenses] [--no-be-activate] [--no-index] [--no-refresh]

    [--no-backup-be | --require-backup-be] [--backup-be-name \fIname\fR]

    [--deny-new-be | --require-new-be] [--be-name \fIname\fR]

    [--reject \fIpkg_fmri_pattern\fR ...] \fIpkg_fmri_pattern\fR ...

.fi

.LP

.nf

/usr/bin/pkg uninstall [-nvq] [--no-be-activate] [--no-index]

    [--no-backup-be | --require-backup-be] [--backup-be-name \fIname\fR]

    [--deny-new-be | --require-new-be] [--be-name \fIname\fR]

    \fIpkg_fmri_pattern\fR ...

.fi

.LP

.nf

/usr/bin/pkg update [-fnvq] [-g \fIpath_or_uri\fR ...] [--accept]

    [--licenses] [--no-be-activate] [--no-index] [--no-refresh]

    [--no-backup-be | --require-backup-be] [--backup-be-name \fIname\fR]

    [--deny-new-be | --require-new-be] [--be-name \fIname\fR]

    [--reject \fIpkg_fmri_pattern\fR ...] [\fIpkg_fmri_pattern\fR ...]

.fi

.LP

.nf

/usr/bin/pkg list [-Hafnsuv] [-g \fIpath_or_uri\fR ...]

    [--no-refresh] [\fIpkg_fmri_pattern\fR ...]

.fi

.LP

.nf

/usr/bin/pkg info [-lr] [-g \fIpath_or_uri\fR ...] [--license]

    [\fIpkg_fmri_pattern\fR ...]

.fi

.LP

.nf

/usr/bin/pkg contents [-Hmr] [-a \fIattribute\fR=\fIpattern\fR ...]

    [-g \fIpath_or_uri\fR ...] [-o \fIattribute\fR ...] [-s \fIsort_key\fR]

    [-t \fIaction_type\fR ...] [\fIpkg_fmri_pattern\fR ...]

.fi

.LP

.nf

/usr/bin/pkg search [HIaflpr] [-o \fIattribute\fR ...]

    [-s \fIrepo_uri\fR] \fIquery\fR

.fi

.LP

.nf

/usr/bin/pkg verify [-Hqv] [\fIpkg_fmri_pattern\fR ...]

.fi

.LP

.nf

/usr/bin/pkg fix [--accept] [--licenses] [\fIpkg_fmri_pattern\fR ...]

.fi

.LP

.nf

/usr/bin/pkg revert [-nv] [--no-be-activate]

    [--no-backup-be | --require-backup-be] [--backup-be-name \fIname\fR]

    [--deny-new-be | --require-new-be] [--be-name \fIname\fR]

    (--tagged \fItag-name\fR ... | \fIpath-to-file\fR ...)

.fi

.LP

.nf

/usr/bin/pkg mediator [-aH] [-F \fIformat\fR] [\fImediator\fR ...]

.fi

.LP

.nf

usr/bin/pkg set-mediator [-nv] [-I \fIimplementation\fR]

    [-V \fIversion\fR] [--no-be-activate]

    [--no-backup-be | --require-backup-be] [--backup-be-name \fIname\fR]

    [--deny-new-be | --require-new-be] [--be-name \fIname\fR]

    \fImediator\fR ...

.fi

.LP

.nf

/usr/bin/pkg unset-mediator [-nvIV] [--no-be-activate]

    [--no-backup-be | --require-backup-be] [--backup-be-name \fIname\fR]

    [--deny-new-be | --require-new-be] [--be-name \fIname\fR]

    \fImediator\fR ...

.fi

.LP

.nf

/usr/bin/pkg variant [-H] [\fIvariant_spec\fR]

.fi

.LP

.nf

/usr/bin/pkg change-variant [-nvq] [-g \fIpath_or_uri\fR ...]

    [--accept] [--licenses] [--no-be-activate]

    [--no-backup-be | --require-backup-be] [--backup-be-name \fIname\fR]

    [--deny-new-be | --require-new-be] [--be-name \fIname\fR]

    \fIvariant_spec\fR=\fIinstance\fR ...

.fi

.LP

.nf

/usr/bin/pkg facet [-H] [\fIfacet_spec\fR]

.fi

.LP

.nf

/usr/bin/pkg change-facet [-nvq] [-g \fIpath_or_uri\fR ...]

    [--accept] [--licenses] [--no-be-activate]

    [--no-backup-be | --require-backup-be] [--backup-be-name \fIname\fR]

    [--deny-new-be | --require-new-be] [--be-name \fIname\fR]

    \fIfacet_spec\fR=[True|False|None] ...

.fi

.LP

.nf

/usr/bin/pkg avoid [\fIpkg_fmri_pattern\fR ...]

.fi

.LP

.nf

/usr/bin/pkg unavoid [\fIpkg_fmri_pattern\fR ...]

.fi

.LP

.nf

/usr/bin/pkg freeze [-n] [-c \fIreason\fR] [\fIpkg_fmri_pattern\fR] ...

.fi

.LP

.nf

/usr/bin/pkg unfreeze [-n] [\fIpkg_name_pattern\fR] ...

.fi

.LP

.nf

/usr/bin/pkg property [-H] [\fIpropname\fR ...]

.fi

.LP

.nf

/usr/bin/pkg set-property \fIpropname\fR \fIpropvalue\fR

.fi

.LP

.nf

/usr/bin/pkg add-property-value \fIpropname\fR \fIpropvalue\fR

.fi

.LP

.nf

/usr/bin/pkg remove-property-value \fIpropname\fR \fIpropvalue\fR

.fi

.LP

.nf

/usr/bin/pkg unset-property \fIpropname\fR ...

.fi

.LP

.nf

/usr/bin/pkg publisher [-HPn] [\fIpublisher\fR ...]

.fi

.LP

.nf

/usr/bin/pkg set-publisher [-Ped] [-k \fIssl_key\fR] [-c \fIssl_cert\fR]

    [-g \fIorigin_to_add\fR | --add-origin \fIorigin_to_add\fR ...]

    [-G \fIorigin_to_remove\fR | --remove-origin \fIorigin_to_remove\fR ...]

    [-m \fImirror_to_add\fR | --add-mirror \fImirror_to_add\fR ...]

    [-M \fImirror_to_remove\fR | --remove-mirror \fImirror_to_remove\fR ...]

    [-p \fIrepo_uri\fR] [--enable] [--disable] [--no-refresh]

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

    [--search-after \fIpublisher\fR] [--search-before \fIpublisher\fR]

    [--search-first]

    [--approve-ca-cert \fIpath_to_CA\fR]

    [--revoke-ca-cert \fIhash_of_CA_to_remove\fR]

    [--unset-ca-cert \fIhash_of_CA_to_remove\fR]

    [--set-property \fIname_of_property\fR=\fIvalue\fR]

    [--add-property-value \fIname_of_property\fR=\fIvalue_to_add\fR]

    [--remove-property-value \fIname_of_property\fR=\fIvalue_to_remove\fR]

    [--unset-property \fIname_of_property_to_delete\fR]

    [\fIpublisher\fR]

.fi

.LP

.nf

/usr/bin/pkg unset-publisher \fIpublisher\fR ...

.fi

.LP

.nf

/usr/bin/pkg history [-Hl] [-t [\fItime\fR | \fItime\fR-\fItime\fR],...]

    [-o \fIcolumn\fR,...] [-n \fInumber\fR]

.fi

.LP

.nf

/usr/bin/pkg purge-history

.fi

.LP

.nf

/usr/bin/pkg rebuild-index

.fi

.LP

.nf

/usr/bin/pkg update-format

.fi

.LP

.nf

/usr/bin/pkg version

.fi

.LP

.nf

/usr/bin/pkg help

.fi

.LP

.nf

/usr/bin/pkg image-create [-FPUfz] [--force]

    [--full | --partial | --user] [--zone]

    [-k \fIssl_key\fR] [-c \fIssl_cert\fR]

    [--no-refresh] [--variant \fIvariant_spec\fR=\fIinstance\fR ...]

    [-g \fIpath_or_uri\fR | --origin \fIpath_or_uri\fR ...]

    [-m \fIuri\fR | --mirror \fIuri\fR ...]

    [--facet \fIfacet_spec\fR=(True|False) ...]

    [(-p | --publisher) [\fIname\fR=]\fIrepo_uri\fR] \fIdir\fR

.fi

.SH DESCRIPTION

.sp

.LP

\fBpkg\fR is the retrieval client for the Image Packaging System. With a valid configuration, \fBpkg\fR 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 can make their packages available at one or more repositories, or in package archives. \fBpkg\fR retrieves packages from a publisher's repository or package archives and installs the packages into an image.

.sp

.LP

A publisher name identifies a person, group of persons, or an organization as the source of one or more packages. To avoid publisher name collisions and help identify the publisher, a best practice is to use a domain name that represents the entity publishing the packages as a publisher name.

.sp

.LP

A repository is a location where clients can publish and retrieve package content (files contained within the package such as programs and documents) and metadata (information about the package such as its name and description). As an example, a publisher named \fBexample.org\fR might have their repository located at the URI \fBhttp://example.org/repository\fR.

.sp

.LP

\fBpkg\fR can also uninstall packages, refresh publisher metadata (such as the list of available packages), validate package installation in an image, and query the image for various tokens. These queries can also be made of \fBpkg\fR(5) repositories.

.sp

.LP

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.

.SH OPTIONS

.sp

.LP

The following options are supported:

.sp

.ne 2

.mk

.na

\fB-R\fR \fIdir\fR

.ad

.sp .6

.RS 4n

Operate on the image rooted at directory \fIdir\fR. If no directory was specified or determined based on environment, the default is /. See the "Environment Variables" section for more information.

.RE

.sp

.ne 2

.mk

.na

\fB--help\fR or \fB-?\fR

.ad

.sp .6

.RS 4n

Display a usage message.

.RE

.SH SUB-COMMANDS

.sp

.LP

The following subcommands are supported:

.sp

.ne 2

.mk

.na

\fBrefresh\fR [\fB--full\fR] [\fIpublisher\fR ...]\fR

.ad

.sp .6

.RS 4n

Updates the client's list of available packages and publisher metadata for each publisher specified. If no publishers are specified, the operation is performed for all publishers.

.sp

With \fB--full\fR, force a full retrieval of all publisher metadata, instead of attempting an incremental update, and request that any proxies used during the operation ignore cached data. This option exists for troubleshooting purposes and should not be used on a regular basis.

.RE

.sp

.ne 2

.mk

.na

\fBinstall\fR [\fB-nvq\fR] [\fB-g\fR \fIpath_or_uri\fR ...] [\fB--accept\fR] [\fB--licenses\fR] [\fB--no-be-activate\fR] [\fB--no-index\fR] [\fB--no-refresh\fR] [\fB--no-backup-be\fR | \fB--require-backup-be\fR] [\fB--backup-be-name\fR \fIname\fR] [\fB--deny-new-be\fR | \fB--require-new-be\fR] [\fB--be-name\fR \fIname\fR] [\fB--reject\fR \fIpkg_fmri_pattern\fR ...] \fIpkg_fmri_pattern\fR ...\fR

.ad

.sp .6

.RS 4n

Installs and updates packages to the newest version that match \fIpkg_fmri_pattern\fR allowed by the packages installed in the image. To explicitly request the latest version of a package, use \fBlatest\fR for the version portion of \fIpkg_fmri_pattern\fR. For example, specify \fBvim@latest\fR.

.sp

Some configuration files might be renamed or replaced during the installation 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 \fBpkg\fR(5).

.sp

If a package is on the avoid list, installing it removes it from that list.

.sp

With \fB-g\fR, temporarily add the specified package repository or archive to the list of sources in the image from which to retrieve package data. If packages from the specified sources are also available from configured publishers in the image, the client will retrieve content for those packages from the specified sources only. When deciding which version of a package to use, publishers configured in the image, but not found in the given sources take precedence. After install or update, any packages provided by publishers not found in the image are added to the image configuration without an origin. This option can be specified multiple times.

.sp

With \fB-n\fR, perform a trial run of the operation with no package changes made.

.sp

With \fB-q\fR, hide progress messages during the requested operation.

.sp

With \fB-v\fR, issue verbose progress messages during the requested operation, and display detailed planning information (such as changing facets, mediators, and variants). This option can be specified multiple times to increase the amount of planning information displayed.

.sp

With \fB--accept\fR, 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 installation operation fails.

.sp

With \fB--licenses\fR, display all of the licenses for the packages that are installed or updated as part of this operation.

.sp

With \fB--no-backup-be\fR, do not create a backup boot environment.

.sp

With \fB--no-be-activate\fR, if a boot environment is created, do not set it as the active BE on the next boot. See \fBbeadm\fR(1M) for more information.

.sp

With \fB--no-index\fR, do not update the search indices after the operation has completed successfully.

.sp

With \fB--no-refresh\fR, do not attempt to contact the repositories for the image's publishers to retrieve the newest list of available packages and other metadata.

.sp

With \fB--backup-be-name\fR, name the created backup boot environment using the given argument. Use of \fB--backup-be-name\fR implies \fB--require-backup-be\fR. See also \fBbeadm\fR(1M).

.sp

With \fB--be-name\fR, rename the newly created boot environment to be the argument given. Use of \fB--be-name\fR implies \fB--require-new-be\fR. See also \fBbeadm\fR(1M).

.sp

With \fB--require-backup-be\fR, always create a backup boot environment if a new boot environment will not be created. Without this option, a backup boot environment is created based on image policy. See \fBbe-policy\fR in "Image Properties" below for an explanation of when backup boot environments are created automatically.

.sp

With \fB--require-new-be\fR, always create a new boot environment. Without this option, a boot environment is created based on image policy. See \fBbe-policy\fR in "Image Properties" below for an explanation of when boot environments are created automatically. This option cannot be combined with \fB--require-backup-be\R.

.sp

With \fB--deny-new-be\fR, do not create a new boot environment. The operation will not be performed if a new boot environment is required.

.sp

With \fB--reject\fR, prevent packages with names matching the given pattern from being installed. If matching packages are already installed, they are removed as part of this operation. Rejected packages that are the target of group dependencies are placed on the avoid list.

.RE

.sp

.ne 2

.mk

.na

\fBuninstall\fR [\fB-nvq\fR] [\fB--no-be-activate\fR] [\fB--no-index\fR] [\fB--no-backup-be\fR | \fB--require-backup-be\fR] [\fB--backup-be-name\fR \fIname\fR] [\fB--deny-new-be\fR | \fB--require-new-be\fR] [\fB--be-name\fR \fIname\fR] \fIpkg_fmri_pattern\fR ...\fR

.ad

.sp .6

.RS 4n

Removes installed packages that match \fIpkg_fmri_pattern\fR.

.sp

If a package is the subject of a group dependency, uninstalling it  places it on the avoid list. See the \fBavoid\fR subcommand below.

.sp

For all other options, refer to the \fBinstall\fR command above for usage and their effects.

.RE

.sp

.ne 2

.mk

.na

\fBupdate\fR [\fB-fnvq\fR] [\fB-g\fR \fIpath_or_uri\fR ...] [\fB--accept\fR] [\fB--licenses\fR] [\fB--no-be-activate\fR] [\fB--no-index\fR] [\fB--no-refresh\fR] [\fB--no-backup-be\fR | \fB--require-backup-be\fR] [\fB--backup-be-name\fR \fIname\fR] [\fB--deny-new-be\fR | \fB--require-new-be\fR] [\fB--be-name\fR \fIname\fR] [\fB--reject\fR \fIpkg_fmri_pattern\fR ...] [\fIpkg_fmri_pattern\fR ...]\fR

.ad

.sp .6

.RS 4n

With no arguments, or if asterisk (*) 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. To explicitly request the latest version of a package, use \fBlatest\fR for the version portion of \fIpkg_fmri_pattern\fR. For example, specify \fBvim@latest\fR.

.sp

If \fIpkg_fmri_pattern\fR is provided, \fBupdate\fR replaces packages that are installed, and that match \fIpkg_fmri_pattern\fR, with the newest version allowed by the patterns and the constraints imposed on the system by installed packages and publisher configuration. Versions older or newer than what is already installed can be specified to perform in-place downgrades or upgrades of specific packages. Updating specific packages across package rename or obsolete boundaries is not supported.

.sp

Any preserved configuration files that are part of packages to be downgraded by \fBupdate\fR and that have been changed since the original version was installed are renamed using the extension \fB\&.update\fR. For more information about how the package system determines which files to preserve, and how these files are preserved during package upgrades, see "File Actions" in \fBpkg\fR(5).

.sp

With the \fB-f\fR option, do not execute the client up-to-date check when updating all installed packages.

.sp

For all other options, refer to the \fBinstall\fR command above for usage and their effects.

.RE

.sp

.ne 2

.mk

.na

\fBlist\fR [\fB-Hafnsuv\fR] [\fB-g\fR \fIpath_or_uri\fR ...] [\fB--no-refresh\fR] [\fIpkg_fmri_pattern\fR ...]\fR

.ad

.sp .6

.RS 4n

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 three columns:

.sp

.in +2

.nf

NAME (PUBLISHER)            VERSION           IFO

system/core-os              0.5.11-0.169      i--

x11/wm/fvwm (fvwm.org)      2.6.1-3           i--

.fi

.in -2

The first column contains the name of the package. If the publisher from which the package is installed (or available, if not installed) is not the first in the publisher search order, 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 \fBpkg\fR(5) for information about release and branch versions.

.sp

.LP

The last column contains a set of flags that show the status of the package:

.RS +4

.TP

.ie t \(bu

.el o

An \fBi\fR in the \fBI\fR column shows that the package is installed.

.RE

.RS +4

.TP

.ie t \(bu

.el o

An \fBf\fR in the \fBF\fR column shows that the package is frozen.

.RE

.RS +4

.TP

.ie t \(bu

.el o

An \fBo\fR in the \fBO\fR column shows that the package is obsolete. An \fBr\fR in the \fBO\fR column shows that the package has been renamed (a form of obsoletion).

.RE

With \fB-H\fR, omit the headers from the listing.

.sp

With \fB-a\fR, 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 allowed by any installed incorporations and the image's variants is listed. Without \fB-a\fR, list only installed packages.

.sp

With \fB-f\fR and \fB-a\fR, list all versions of all packages for all variants regardless of incorporation constraints or installed state. To explicitly list the latest version of a package when using these options, use \fBlatest\fR for the version portion of \fIpkg_fmri_pattern\fR. For example, specify \fBvim@latest\fR.

.sp

With \fB-g\fR, use the specified package repository or archive as the source of package data for the operation. This option can be specified multiple times. Use of \fB-g\fR implies \fB-a\fR if \fB-n\fR is not specified.

.sp

With \fB-n\fR, display the newest versions of all known packages, regardless of installed state.

.sp

With \fB-s\fR, display a one-line short-form giving the package name and summary. This option can be used with \fB-a\fR, \fB-n\fR, \fB-u\fR or \fB-v\fR.

.sp

With \fB-u\fR, list only packages with newer versions available. This option cannot be used with \fB-g\fR.

.sp

With \fB-v\fR, show full package FMRIs, including publisher and complete version, all in the first column (the VERSION column disappears). This option can be used with \fB-a\fR, \fB-n\fR, or \fB-u\fR.

.sp

With \fB--no-refresh\fR, do not attempt to contact the repositories for the image's publishers to retrieve the newest list of available packages.

.RE

.sp

.ne 2

.mk

.na

\fBinfo\fR [\fB-lr\fR] [\fB-g\fR \fIpath_or_uri\fR ...] [\fB--license\fR] [\fIpkg_fmri_pattern\fR ...]\fR

.ad

.sp .6

.RS 4n

Display information about packages in a human-readable form. Multiple FMRI patterns can be specified. With no patterns, display information on all installed packages in the image.

.sp

With \fB-g\fR, use the specified package repository or archive as the source of package data for the operation. This option can be specified multiple times. Use of \fB-g\fR implies \fB-r\fR.

.sp

With \fB-l\fR, only display information for installed packages. This is the default.

.sp

With \fB-r\fR, match packages based on the newest available versions, retrieving information for packages not currently installed (if necessary) from the repositories of the image's configured publishers. At least one package must be specified when using this option. Without \fB-r\fR, only installed packages are displayed by default.

.sp

With \fB--license\fR, display the license texts for the packages. This option can be combined with \fB-l\fR or \fB-r\fR.

.RE

.sp

.ne 2

.mk

.na

\fBcontents\fR [\fB-Hmr\fR] [\fB-a\fR \fIattribute\fR=\fIpattern\fR ...] [\fB-g\fR \fIpath_or_uri\fR ...] [\fB-o\fR \fIattribute\fR,...] [\fB-s\fR \fIsort_key\fR] [\fB-t\fR \fIaction_type\fR ...] [\fIpkg_fmri_pattern\fR ...]\fR

.ad

.sp .6

.RS 4n

Display the contents (action attributes) of packages in the current image. By default, only the \fBpath\fR attribute is displayed. The attributes displayed can be determined with the \fB-o\fR option. The \fB-o\fR option can be specified multiple times, or multiple attributes can be specified as the argument to one \fB-o\fR option by separating the attribute names with commas. Only actions that have the requested attributes are displayed. The \fB-m\fR option can also be used, as a shorthand for \fB-Ho action.raw\fR.

.sp

With \fB-a\fR, limit the output to those actions that have an attribute named in the option argument with a value that matches the (glob) pattern in the option argument (following the attribute name with an equals sign). If multiple \fB-a\fR options are given, then actions matching any of them are displayed.

.sp

With \fB-g\fR, use the specified package repository or archive as the source of package data for the operation. This option can be specified multiple times. Use of \fB-g\fR implies \fB-r\fR.

.sp

With \fB-r\fR, match packages based on the newest available versions, retrieving information for packages not currently installed (if necessary) from the repositories of the image's configured publishers. At least one package must be specified when using this option. Without \fB-r\fR, only installed packages are displayed by default.

.sp

With \fB-s\fR, sort actions by the specified action attribute. If not provided, the default is to sort by path or by the first attribute specified by the \fB-o\fR option. The \fB-s\fR option can be specified multiple times.

.sp

With \fB-t\fR, only list actions of the type specified. Multiple types can be specified in a comma-separated list. This option can be specified multiple times.

.sp

With \fB-H\fR, omit the headers from the listing.

.sp

With no arguments, the output includes all installed packages. Alternatively, multiple FMRI patterns can be specified, which restricts the display to the contents of the matching packages. When using \fB-r\fR, one or more \fIpkg_fmri_pattern\fR must be specified.

.sp

Several special pseudo attribute names are available for convenience:

.sp

.ne 2

.mk

.na

\fBaction.hash\fR

.ad

.RS 17n

.rt  

Corresponds to the value of the action's hash, if the action carries a payload.

.RE

.sp

.ne 2

.mk

.na

\fBaction.key\fR

.ad

.RS 17n

.rt  

Corresponds to the value of the action's key attribute. For example, for a file action, this is the path to the file.

.RE

.sp

.ne 2

.mk

.na