'\" te

.\" Copyright (c) 2007, 2013, Oracle and/or its affiliates. All rights reserved.

.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 [-q] [--full] [\fIpublisher\fR ...]

.fi

.LP

.nf

/usr/bin/pkg install [-nvq] [-C \fIn\fR] [-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] [-C \fIn\fR] [--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] [-C \fIn\fR] [-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 [-Hafnqsuv] [-g \fIpath_or_uri\fR]...

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

.fi

.LP

.nf

/usr/bin/pkg info [-lqr] [-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[,\fIattribute\fR]...]...

    [-s \fIsort_key\fR] [-t \fIaction_name\fR[,\fIaction_name\fR]...]...

    [\fIpkg_fmri_pattern\fR ...]

.fi

.LP

.nf

/usr/bin/pkg search [-HIaflpr]

    [-o \fIattribute\fR[,\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

.fi

.LP

.nf

/usr/bin/pkg change-variant [-nvq] [-C \fIn\fR] [-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_name\fR=\fIvalue\fR ...

.fi

.LP

.nf

.fi

.LP

.nf

/usr/bin/pkg change-facet [-nvq] [-C \fIn\fR] [-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_name\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] [-F \fIformat\fR] [\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]...

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

    [--proxy \fIproxy_to_use\fR] \fIpublisher\fR

.fi

.LP

.nf

/usr/bin/pkg set-publisher -p \fIrepo_uri\fR [-Ped]

    [-k \fIssl_key\fR] [-c \fIssl_cert\fR] [--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]

    [--proxy \fIproxy_to_use\fR] [\fIpublisher\fR]

.fi

.LP

.nf

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

.fi

.LP

.nf

/usr/bin/pkg history [-HNl]

    [-t \fItime\fR | \fItime\fR-\fItime\fR[,\fItime\fR | \fItime\fR-\fItime\fR]...]...

    [-o \fIcolumn\fR[,\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_name\fR=\fIvalue\fR]...

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

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

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

    [--facet \fIfacet_name\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\fB-?\fR\fR

.ad

.br

.na

\fB\fB--help\fR\fR

.ad

.sp .6

.RS 4n

Display a usage message.

.RE

.sp

.ne 2

.mk

.na

\fB\fB-R\fR \fIdir\fR\fR

.ad

.br

.na

\fB\fB--image-dir\fR \fIdir\fR\fR

.ad

.sp .6

.RS 4n

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

.RE

.SH SUB-COMMANDS

.sp

.LP

The following subcommands are supported:

.sp

.ne 2

.mk

.na

\fB\fBpkg refresh\fR [\fB-q\fR] [\fB--full\fR] [\fIpublisher\fR ...]\fR

.ad

.sp .6

.RS 4n

Update the client's list of available packages and publisher metadata for all publishers.

.sp

.ne 2

.mk

.na

\fB\fIpublisher\fR\fR

.ad

.sp .6

.RS 4n

Update the client's list of available packages and publisher metadata only for the specified publishers.

.RE

.sp

.ne 2

.mk

.na

\fB\fB-q\fR\fR

.ad

.sp .6

.RS 4n

Hide progress messages during the requested operation.

.RE

.sp

.ne 2

.mk

.na

\fB\fB--full\fR\fR

.ad

.sp .6

.RS 4n

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

.RE

.sp

.ne 2

.mk

.na

\fB\fBpkg install\fR [\fB-nvq\fR] [\fB-C\fR \fIn\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

Install and update the specified 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

Packages are selected based on publisher search order and stickiness. See the \fBpkg publisher\fR and \fBpkg set-publisher\fR commands for information about search order and stickiness. If the \fIpkg_fmri_pattern\fR does not specify the publisher, the first publisher that provides a matching package is used as the installation source. If that publisher does not provide a version of the package that can be installed in this image, then the installation operation fails. Use the \fBpkg list -a\fR command to see which publishers provide a version of the package that can be installed in this image.

.sp

If more than one \fIpkg_fmri_pattern\fR is specified, and if any of the specified packages cannot be installed in this image, then none of the specified packages will be installed.

.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 the \fBpkg\fR(5) man page.

.sp

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

.sp

.ne 2

.mk

.na

\fB\fB-g\fR \fIpath_or_uri\fR\fR

.ad

.sp .6

.RS 4n

Temporarily add the specified package repository or archive to the list of sources in the image from which to retrieve package data. Repositories that require a client SSL certificate cannot be used with this option. This option can be specified multiple times.

.sp

When deciding which version of a package to use, publishers configured in the image, but not found in the specified \fIpath_or_uri\fR sources, take precedence. If the version of the package to be installed is provided by a publisher configured in the image and by a \fIpath_or_uri\fR source, the client retrieves the content for that package from the \fIpath_or_uri\fR sources. After installation or update, any packages provided by publishers not configured in the image are added to the image configuration without an origin. Use the \fBpkg publisher\fR command to see which publishers are configured in the image.

.RE

.sp

.ne 2

.mk

.na

\fB\fB-n\fR\fR

.ad

.sp .6

.RS 4n

Perform a trial run of the operation with no package changes made.

.RE

.sp

.ne 2

.mk

.na

\fB\fB-v\fR\fR

.ad

.sp .6

.RS 4n

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.

.RE

.sp

.ne 2

.mk

.na

\fB\fB-q\fR\fR

.ad

.sp .6

.RS 4n

Hide progress messages during the requested operation.

.RE

.sp

.ne 2

.mk

.na

\fB\fB-C\fR \fIn\fR\fR

.ad

.sp .6

.RS 4n

Specify the number of child images to update in parallel. When recursing into child images (usually zones), update at most \fIn\fR child images in parallel. The default number of child images to update in parallel is 1. If \fIn\fR is 0 or a negative number, all child images are updated in parallel. See also \fBPKG_CONCURRENCY\fR in the "Environment Variables" section.

.RE

.sp

.ne 2

.mk

.na

\fB\fB--accept\fR\fR

.ad

.sp .6

.RS 4n

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.

.RE

.sp

.ne 2

.mk

.na

\fB\fB--licenses\fR\fR

.ad

.sp .6

.RS 4n

Display all of the licenses for the packages that are installed or updated as part of this operation. For updated packages, display the license only if the license has changed.

.RE

.sp

.ne 2

.mk

.na

\fB\fB--no-backup-be\fR\fR

.ad

.sp .6

.RS 4n

Do not create a backup boot environment.

.RE

.sp

.ne 2

.mk

.na

\fB\fB--no-be-activate\fR\fR

.ad

.sp .6

.RS 4n

If a boot environment is created, do not set it as the active boot environment on the next boot. See the \fBbeadm\fR(1M) man page for more information.

.RE

.sp

.ne 2

.mk

.na

\fB\fB--no-index\fR\fR

.ad

.sp .6

.RS 4n

Do not update the search indexes after the operation has completed successfully.