NAME

pkgrecv — Image Packaging System content retrieval utility

SYNOPSIS

DESCRIPTION

pkgrecv retrieves all versions of each matching fmri or pattern from the pkg(7) repository or package archive specified by the -s option and optionally republishes the retrieved packages to the package repository or package archive specified by the -d option. By default, packages are retrieved in package repository format suitable for use with pkg(1), pkg.depotd(8), and package publication tools.

Packages that have not changed are not republished. Therefore, the time to update an existing repository depends on the number of new and changed packages.

Use the -m option to specify whether to retrieve all versions of each matching package, or only the newest version of each matching package.

If you do not specify ‘*’ to be retrieved, you might want to specify the -r option to be sure to retrieve all the dependencies of the specified packages.

Note -

After a pkgrecv operation that retrieves packages into a dest_uri, if the dest_uri repository must support pkg search operations, run pkgrepo refresh on that repository to update search indexes.

OPTIONS

The following options are supported:

-h

Display a usage message.

-a

Store the retrieved package data in a pkg(7) archive at the location specified by the -d option. The file specified by -d cannot already exist. The -a option can be used only with file system based destinations. Although not required, using a file extension of ‘.p5p’ (for example, archive.p5p) is strongly suggested. The -a option cannot be combined with the --raw option.

-c cache_dir

Specify the path to a directory that will be used to cache downloaded content. If this directory is not supplied, the client automatically selects a cache directory. In the case where a download is interrupted, and a cache directory was automatically chosen, use this option to resume the download. See the Environment Variables section below for details about how to set the location used for temporary data storage.

-d dest_path|dest_uri

Specify the file system path or URI where the retrieved packages should be republished. If -a is specified, this destination must be a package archive that does not already exist. If -a is not specified, this destination must be a package repository that already exists. Use the pkgrepo(1) command to create a new package repository. If -d is not specified, the value of PKG_DEST is used. See Environment Variables below.

-k

Keep the retrieved package content compressed. This option is ignored when republishing. Compressed package content should not be used with pkgsend.

-m match

Control which versions of packages are retrieved if pattern is specified or if fmri is not fully specified. For this description, the following four example packages exist in the source specified by the -s option. In these FMRI, the characters between the @ and the : denote the numbered package version, and the characters from the : to the end denote the timestamp portion of the version string.

pkg://omnios/package/pkg@0.5.11-151038.1:20120904T180335Z
pkg://omnios/package/pkg@0.5.11-151038.1:20120903T170234Z
pkg://omnios/package/pkg@0.5.11-151038.0:20120820T165108Z
pkg://omnios/package/pkg@0.5.11-151038.0:20120819T155007Z

all-timestamps

Retrieve all versions of each matching fmri or pattern (implies all-versions). This is the default behaviour if the -m option is not specified. In the example above, all four packages are retrieved.

all-versions

Retrieve the latest timestamp for each version of each matching fmri or pattern. In the example above, the following two packages are retrieved:

pkg://omnios/package/pkg@0.5.11-151038.1:20120904T180335Z
pkg://omnios/package/pkg@0.5.11-151038.0:20120820T165108Z

latest

Retrieve only the newest version of each matching fmri or pattern. In the example above, only the following package is retrieved:

pkg://omnios/package/pkg@0.5.11-151038.1:20120904T180335Z

--mog-file file_path

Specifies a file containing pkgmogrify(1) transforms to be applied to the manifest of each package before it is copied to the destination package repository. ‘-’ can be specified to use stdin as input. If both files and ‘-’ are specified together, ‘-’ will be ignored and only files specified are used. Use of this option will automatically cause any existing package signatures to be dropped from the package. Adding new hashable actions such as files and licenses is not allowed. This option can be specified multiple times. This option may not be combined with ---clone.

-n

Perform a trial run with no changes made.

-p publisher

Only clone the specified publisher. This option can be specified multiple times. The -p option is valid only with the --clone option.

-r

Recursively retrieve all dependencies for each matching fmri or pattern.

-s src_path|src_uri

Specify the file system path or URI of a pkg(7) repository or package archive from which to receive package data. If -s is not specified, the value of PKG_SRC is used. See Environment Variables below.

-v

Display verbose output, including the number of packages retrieved and their full FMRIs, the number of files retrieved, and the estimated size of the transfer.

--key src_key

Specify a client SSL key file to use for package retrieval from the source HTTPS repository.

--cert src_cert

Specify a client SSL certificate file to use for package retrieval from the source HTTPS repository.

--dkey dest_key

Specify a client SSL key file to use for package publication to the destination HTTPS repository.

--dcert dest_cert

Specify a client SSL certificate file to use for package publication to the destination HTTPS repository.

--clone

Make an exact copy of the source repository. By default, the clone operation succeeds only if publishers in the source repository are also present in the destination. To limit the clone operation to specified publishers, use the -p option. Publishers specified by using the -p option are added to the destination repository if they are not already present. Packages that are in the destination repository but not in the source repository are removed. The clone operation leaves the destination repository altered if an error occurs. Therefore, the destination repository should be in its own ZFS dataset, and a snapshot should be created prior to performing the clone operation.

--newest

List the most recent versions of the packages available from the repository specified by the -s option. All other options are ignored.

--raw

Retrieve and store the raw package data in a set of directory structures by stem and version at the location specified by -d. The --raw option can be used only with file system based destinations. This package data can be used to conveniently modify and republish packages, perhaps by correcting file contents or providing additional package metadata. The --raw option cannot be combined with -a.

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.

99

An unanticipated exception occurred.

EXAMPLES

Example 1 List Newest Packages

List the newest packages available from the repository on the system named test.

pkgrecv -s http://test --newest
pkg://omnios/system/library/c++-runtime@0.5.11,151038.0:20120921T190358Z
pkg://omnios/system/library/freetype-2@2.4.8,151038.0:20120109T215840Z
pkg://omnios/system/library/math@0.5.11,151038.0:20120921T190432Z

Example 2 Retrieve Raw Package Data

Receive the c++-runtime package from Example 1 in a format suitable for use with pkgsend publish.

pkgrecv -s http://test \
    -d /local/repo --raw \
    c++-runtime@0.5.11,151038.0:20120921T190358Z
    Processing packages for publisher omnios ...
    Retrieving and evaluating 1 package(s)
    PROCESS       ITEMS     GET (MB)    SEND (MB)
    Completed       1/1      3.5/3.5      0.0/0.0
ls /local/repo
    pkg5.repository  publisher  system%2Flibrary%2Fc%2B%2B-runtime

Example 3 Retrieve Dependencies From a System

Receive the package editor/vim and all of its dependencies from the system named test.

pkgrecv -s http://test -d /local/repo -r editor/vim

Example 4 Retrieve Only the Latest Version

Receive only the latest version of the package editor/vim from the system named test.

pkgrecv -s http://test -d /local/repo -m latest -v \
    editor/vim
Processing packages for publisher omnios ...
Retrieving and evaluating 1 package(s)
Retrieving packages ...
Packages to add:       1
Files to retrieve:    1557
Estimated transfer size: 9.21 MB
Packages to transfer:
editor/vim@7.3.600,151038.0:20120904T172128Z
    PROCESS       ITEMS     GET (MB)    SEND (MB)
    Completed       1/1      9.2/9.2    25.4/25.4

Example 5 Retrieve All Versions and Republish Remotely

Receive all versions of the package library/zlib from the system named test and republish it to a remote repository on the system named remote.

pkgrecv -s http://test -d http://remote:10000 \
    -m all-versions library/zlib

Example 6 Retrieve Dependencies From a Repository

Receive the package editor/gnu-emacs and all of its dependencies from the repository located at /export/repo.

pkgrecv -s /export/repo -d /local/repo -r editor/gnu-emacs

Example 7 Retrieve Additional Packages and Changed Content

Receive all packages that do not already exist and all changed content from the repository located at https://pkg.omnios.org/bloody/core/ to the repository located at /export/bloody.

pkgrecv -s https://pkg.omnios.org/bloody/core/ \
    -d /export/bloody -m all-timestamps '*'

Receive all packages that do not already exist and all changed content from the secure repository located at https://pkg.omnios.org/bloody/core/ to the repository located at /export/bloody.

pkgrecv -s https://pkg.omnios.org/bloody/core/ \
    -d /export/bloody -m all-timestamps \
    --key /var/pkg/ssl/Your-Organisation.key.pem \
    --cert /var/pkg/ssl/Your-Organisation.certificate.pem '*'

Example 8 Create a Package Archive

Create a package archive containing the package editor/gnu-emacs and all of its dependencies from the repository located at http://example.com:10000.

pkgrecv -s http://example.com:10000 -d /my/emacs.p5p -a \
    -r editor/gnu-emacs

Example 9 Copy Packages From an Archive to a Repository

Copy all of the packages in a package archive to an existing repository located at /export/repo.

pkgrecv -s /my/archive.p5p -d /export/repo '*'

Example 10 Change publisher name

Change the publisher name of the package ‘foo’ and all its dependencies into ‘extra’ during republishing.

echo '<transform set name=pkg.fmri -> edit value
    (pkg://).*?(/.*) \1extra\2' | \
    pkgrecv -s repo1 -d repo2 --mog-file - foo

ENVIRONMENT VARIABLES

The following environment variables are supported:

PKG_DEST

The path of a directory to save the retrieved package to, or the file system path or URI of a repository or package archive where the packages will be copied.

PKG_SRC

A URI or file system path representing the location of a pkg(7) repository or package archive from which to retrieve packages.

TMPDIR

The absolute path of the directory where temporary data should be stored during program execution. If not set, the default is to store temporary data in /var/tmp.

INTERFACE STABILITY

The command line interface of pkgrecv is Uncommitted. The output of pkgrecv is Not-An-Interface and may change at any time.

SEE ALSO

pkg(1), pkgrepo(1), pkgsend(1), pkg(7), pkg.depotd(8)