NAME

SYNOPSIS

DESCRIPTION

pkg_add can be used to install new packages, to replace existing packages with other flavors (option -r) or to update packages to newer versions (option -u).

Details of packing-list internals are documented in pkg_create(1).

pkg_add will syslog(3) installations and updates by default (but see pkg.conf(5)).

If a package is digitally signed:

• pkg_add checks that its packing-list is not corrupted and matches the cryptographic signature stored within.
• pkg_add verifies that the signature was emitted by a valid user certificate, signed by one of the authorities in /etc/ssl/pkgca.pem
• pkg_add verifies that each file matches its sha256 checksum right after extraction, before doing anything with it.
• pkg_add verifies that any dangerous mode or owner is registered in the packing-list.

In normal mode, the package names given on the command lines are names of new packages that pkg_add should install, without ever deinstalling existing packages.

In replacement mode, the package names given on the command lines are names of new packages that pkg_add should install, possibly replacing existing installed packages.

In update mode, the package names given on the command lines are names of installed packages, and pkg_add should figure out newer package names for these, then replace the old packages with the new.

Each package name may be specified as a filename (which normally consists of the package name itself plus the “.tgz” suffix) or a URL referring to FTP, HTTP, HTTPS, or SCP locations. The following examples are valid:

pkg_add -v ftp://ftp.openbsd.org/pub/OpenBSD/2.7/packages/i386/m4-1.4.tgz pkg_add -v scp://login@host/usr/ports/packages/sparc/all/tcl-8.4.7.tgz

If the given package names are not found in the current working directory, pkg_add will search for them in each directory named by the PKG_PATH environment variable. Specifying ‘-’ as a package name causes pkg_add to read from the standard input.

pkg_add also understands ‘stems’, that is, package names without any version specification. For instance, with pkg_add kdelibs, pkg_add will look in the current directory (or the PKG_PATH) for a kdelibs package.

In case of ambiguities, for instance: pkg_add screen (matches screen-4.02 and screen-4.02-static), pkg_add will error out, unless it is invoked in interactive mode (option -i).

To avoid ambiguities, pkg_add supports ‘stems with flavors’, that is, a stem separated from flavors with a double dash. For instance, the previous ambiguity could be resolved by using pkg_add screen-- (matches only the normal flavor) or pkg_add screen--static (matches only the static flavor).

If the environment variable PKG_CACHE is set to a directory name, every package retrieved from a distant location will also be copied here.

Some packages may depend on other packages. When resolving dependencies pkg_add will first look at already installed packages, then match dependencies with the list of packages left to install, then ask the user's opinion in interactive mode, then install default packages that satisfy the dependencies.

Alternatively, it is possible to add packages interactively from within the ftp(1) client, in which case setting PKG_PATH correctly will be necessary for any dependency to be found out and retrieved the same way. For example, the following works:

$ ftp ftp://ftp.openbsd.org/pub/OpenBSD/2.7/packages/i386/
250 CWD command successful
ftp> ls m*
227 Entering Passive Mode (129,128,5,191,164,73)
150 Opening ASCII mode data connection for m*.
m4-1.4.tgz
metamail-2.7.tgz
mh-6.8.4.tgz
mm-1.0.12.tgz
mpeg_lib-1.2.1.tgz
mpeg_play-2.4.tgz
mpg123-0.59q.tgz
mutt-0.95.7i.tgz
226 Transfer complete.
ftp> get m4-1.4.tgz "|pkg_add -v -"

Warning: Since the pkg_add command may execute scripts or programs contained within a package file, your system may be susceptible to “trojan horses” or other subtle attacks from miscreants who create dangerous packages. Be sure the specified package(s) are from trusted sources.

The options are as follows:

-A arch

Assume arch as current machine architecture for any package tests.

-a

Automated package installation; do not record packages as installed manually.

-B pkg-destdir

Set pkg-destdir as the prefix to prepend to any object extracted from the package.

-c

While replacing packages, delete extra configuration file in the old package, mentioned as

@extra file

in the packing-list.

-D name[=value]

Force installation of the package. name is a keyword that states what failsafe should be waived. Recognized keywords include:

allversions

do not trim older p* variants of packages for updates.

arch

architecture recorded in package may not match.

dontmerge

by default, if dependencies are too strict, pkg_add will merge updates together to make sure everything stays in synch. -D dontmerge disables that behavior.

donttie

by default, pkg_add will try to find new files in old packages by comparing the stored sha256, and tie the entries together to avoid extracting files needlessly. -D donttie disables that behavior.

downgrade

don't filter out package versions older than what's currently installed.

installed

in update mode, reinstall an existing package with the same signature.

libdepends

library specifications may not be fulfilled.

nonroot

install even if not running as root.

nosig

do not check digital signatures. Still displays a very prominent message if a signature is found.

paranoid

very safe update: don't run any @exec/@unexec.

repair

attempt to repair installed packages with missing registration data.

scripts

external scripts may fail.

updatedepends

force update even if forward dependencies no longer match.

-i

Switch on interactive mode. pkg_add may ask questions to the user if faced with difficult decisions.

-L localbase

Install a package under localbase. By default, localbase equals /usr/local, and specifying it is not necessary. However, packages can be created using a different localbase (see pkg_create(1)), and those packages can only be installed by using the same localbase. See bsd.port.mk(5) for a description of LOCALBASE.

-l file

Installs packages from the raw output of pkg_info(1), as saved in file. Generally, use with pkg_info -m >file, to reproduce an installation from machine to machine. With -z and -l pkg_add will try its best to reproduce the installation, even if the version numbers don't quite match and even if some packages cannot be found.

-m

Causes pkg_add to always display the progress meter in cases it would not do so by default.

-n

Don't actually install a package, just report the steps that would be taken if it was. Will still copy packages to PKG_CACHE if applicable.

-P type

Check permissions for distribution, where type can be ‘cdrom’ or ‘ftp’.

-Q quick-destdir

Quick and dirty installation under quick-destdir. Contrary to -B pkg-destdir, symbolic links are resolved, and package installation stops at @endfake marker.

-q

Replace package quickly; do not bother with checksums before removing normal files. If used twice, it will not bother with checksums for configuration files either.

-r

Replace existing packages. pkg_add will try to take every precaution to make sure the replacement can proceed before removing the old package and adding the new one, and it should also handle shared libraries correctly. Among other things, pkg_add will refuse to replace packages as soon as it needs to run scripts that might fail (use -D update to force the replacement); pkg_add will also refuse to replace packages when the dependencies don't quite match (use -D updatedepends to force the replacement).

-s

Don't actually install packages, skip as many steps as needed and report only the disk size changes that would happen. Similar to -n, except it also skips fetching full packages and stops at getting the information it needs.

-U

Update dependencies if required before installing the new package(s).

-u

Update the given installed pkgname(s), and anything it depends upon. If no pkgname is given, pkg_add will update all installed packages. This relies on PKG_PATH to figure out the new package names.

-v

Turn on verbose output. Several -v turn on more verbose output. By default, pkg_add is almost completely silent, but it reacts to keyboard status requests (see stty(1)). -v turns on basic messages, -vv adds relevant system operations, -vvv shows most internal computations apart from individual file/directory additions, -vvvv also shows dependencies adjustments, and -vvvvv shows everything.

-x

Disable progress meter.

-z

Fuzzy package addition: pkg_add should do its best to match package names passed on the command line, even if the versions don't match and it will proceed even if some packages can't be found.

By default, when adding packages via FTP, the ftp(1) program operates in “passive” mode. If you wish to use active mode instead, set the FTPMODE environment variable to “active”. If pkg_add consistently fails to fetch a package from a site known to work, it may be because the site does not support passive mode FTP correctly. This is very rare since pkg_add will try active mode FTP if the server refuses a passive mode connection.

Manual installation

It is also possible to tweak the ‘installed manually’ status of a package after the fact. Running pkg_add on an already installed package will tag it as ‘installed manually’, even if it was already there as a dependency of something else, and doubling the -a option will remove the ‘installed manually’ tag from installed packages.

pkg_info(1) can be used to show only manually-installed packages, and pkg_delete(1) can be used to remove dependencies when they are no longer needed.

Technical details

For each new package in an updateset, pkg_add extracts the package's “packing information” (the packing-list, description, and installation/deinstallation scripts) into a special staging directory in /var/tmp (or PKG_TMPDIR if set - see CAVEATS, below) and then runs through the following sequence to fully extract the contents of the package:

1. A check is made to determine if the package is already recorded as installed. If it is, the installation is terminated.
2. A check is made to determine if the package conflicts (from @conflict directives; see pkg_create(1)) with a package already recorded as installed. In non-replacement mode, its installation is terminated.
3. For packages tagged with architecture constraints, pkg_add verifies that the current machine architecture agrees with the constraints.
4. All package dependencies (from @depend and @wantlib directives; see pkg_create(1)) are read from the packing-list. If any of these dependencies are not currently fulfilled, an attempt is made to find a package that meets them and install it, looking first in the current updateset, then in the list of packages to install passed to pkg_add; if no adequate package can be found and installed, the installation is terminated.
5. pkg_add checks for collisions with installed file names, read-only file systems, and enough space to store files.
6. If the package contains an install script (deprecated, @exec is more versatile), it is executed with the following arguments:

   pkg-name

   The name of the package being installed.

   PRE-INSTALL

   Keyword denoting that the script is to perform any actions needed before the package is installed.

   If the install script exits with a non-zero status code, the installation is terminated.

7. The packing-list is used as a guide for extracting files from the package into their final locations.
8. If an install script exists for the package (deprecated), it is executed with the following arguments:

   pkg_name

   The name of the package being installed.

   POST-INSTALL

   Keyword denoting that the script is to perform any actions needed after the package has been installed.

9. After installation is complete, a copy of all package files such as the packing-list, the install and deinstall scripts, the description file is made into /var/db/pkg/<pkg-name> for subsequent possible use by pkg_delete(1) and pkg_info(1). Any package dependencies are recorded in the other packages' /var/db/pkg/<other-pkg>/+REQUIRED_BY file (if the environment variable PKG_DBDIR is set, this overrides the /var/db/pkg/ path shown above).
10. Finally, the staging area is deleted and the program terminates.

Note that it is safe to interrupt pkg_add through SIGINT, SIGHUP, and other signals, as it will safely record an interrupted install as partial-<pkgname>[.n].

When replacing packages, the procedure is slightly different.

1. A check is made to determine if a similar package is already installed. If its signature is identical to that of the new package, no replacement is performed (unless -D installed is specified).
2. A check is made to determine what old package(s) the new package(s) should replace, using conflicts. pkg_add will attempt to update those packages. If they update to the new package(s), nothing needs to be done. If they're part of the list of updatesets to install, the corresponding updatesets will be merged. Otherwise, pkg_add will add them to the current updateset, and rerun update to find suitable update to those packages.
3. A check is made to determine whether the old packages will be deleted without issue, and whether the new packages will install correctly. This includes refusing to run any code (unless -D update), and verifying that the new package still matches dependencies (unless -D updatedepends).
4. Shared libraries deserve special treatment: each shared library from the old packages that does no longer exist in the new packages, but that is required from a wantlib of another package is kept along in a stub package named .libs-<pkgname>.
5. The new packages are extracted to the filesystem, using temporary filenames of the form pkg.XXXXXXX since the old packages are still there. The packing-list is amended to record these names as @temp annotations, in cases the installation fails.
6. The old packages are deleted as usual, except that some packages may still depend on them. Note also that @unexec-delete commands are not executed.
7. The new packages are installed as usual, except that the files are already present and only need to be renamed. Note also that @exec-add commands are not executed.
8. Dependencies from the old packages are adjusted to point to the correct new package.

To update packages in -u mode, pkg_add performs the following steps.

1. Each package name is reduced to its stem, and every package name with matching stem available through PKG_PATH is considered as an update candidate.
2. pkg_add searches for a ‘quirks’ package first, which may contain exceptions to these rules. This special package contains global information, such as packages that can be deleted because they're now part of base, or stem changes.
3. Version matching occurs: unless -D downgrade, only packages with newer versions will be considered as update candidates. Note that version matching is costly, thus PKG_PATH should point to a snapshot of packages for a given version of OpenBSD, similar to the organization on the FTP sites.
4. Candidates are then matched according to their source paths (the subdirectory of the ports dir, plus flavors and multi-packages modifiers), in order to weed out similar packages with distinct options.
5. The signature of the candidate is compared to the signature of the already installed package: identical signatures mean no update needed.
6. If several candidates are left, pkg_add will ask the user in interactive mode, and not perform the update in non-interactive mode.
7. Once a suitable update candidate has been found, pkg_add checks the package dependencies. If necessary, it will install or update them first. Once all dependencies are up-to-date, pkg_add will update the package.

ENVIRONMENT

FTPMODE

Specifies whether ftp(1) should operate in “active” or “passive” mode. The default is “passive”.

FETCH_CMD

Override use of ftp(1). Must point to a command that understands ${FETCH_CMD} -o - url.

FTP_KEEPALIVE

Have ftp(1) send a byte after every FTP_KEEPALIVE seconds, so that incorrectly configured network equipment won't aggressively drop it. See “ftp -k” for more information.

PKG_DBDIR

Where to register packages instead of /var/db/pkg.

PKG_DESTDIR

Value for pkg-destdir, if no -B option is specified; value passed to any INSTALL or REQUIRE script invoked from the package.

PKG_CACHE

If set, any package retrieved from a distant location will be copied to that directory as well.

PKG_PATH

If a given package name cannot be found, the directories named by PKG_PATH are searched. It should contain a series of entries separated by colons. Each entry consists of a directory name. URL schemes such as FTP, HTTP, HTTPS, or SCP are also appropriate. The current directory may be indicated implicitly by an empty directory name, or explicitly by a single period (‘./’).

PKG_TMPDIR

Temporary area where package information files will be extracted, instead of /var/tmp.

SEE ALSO

AUTHORS

Jordan Hubbard

Initial design.

Marc Espie

Complete rewrite.

CAVEATS

If /var/tmp is mounted noexec, you must currently set PKG_TMPDIR to a suitable area, as pkg_add will refuse to install any package that contains executable scripts.