PKG_ADD(1) OpenBSD Reference Manual PKG_ADD(1)
NAME
pkg_add - install software package distributions
SYNOPSIS
pkg_add [-acIinqruvx] [-A arch] [-B pkg-destdir] [-F keywords]
[-L localbase] [-P type] [-Q quick-destdir] pkg-name [...]
DESCRIPTION
The pkg_add command is used to install packages created with the
pkg_create(1) command. Selected packages containing pre-compiled appli-
cations from the /usr/ports tree can be found on the OpenBSD FTP site or
on the official OpenBSD CD.
Note: System distribution files, e.g., base28.tgz, comp28.tgz, are
not packages and may not be installed using pkg_add.
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).
In normal mode, the package names given on the command lines are names of
new packages that pkg_add should install, without ever deinstalling ex-
isting packages.
In replacement mode, the package names given on the command lines are
names of new packages that pkg_add should install, possibly replacing ex-
isting 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, 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 directo-
ry, pkg_add will search for them in each directory named by the PKG_PATH
environment variable. Since a few URL schemes contain colons, pkg_add
relies on each directory ending in a / to split the path correctly.
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 ver-
sion 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).
If the environment variable PKG_CACHE is set, 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 depen-
dencies 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 nec-
essary 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 con-
tained 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 in-
stalled 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.
-F keywords
Force installation of the package. keywords is a comma-separat-
ed list of keywords that state what failsafes should be waived.
These include:
allversions do not trim older p* variants of packages for
updates.
alwaysupdate proceed with an update even if pkg_add can't
find new packages for all installed packages.
arch architecture recorded in package may not match.
boguslibs not all shared libraries are marked with @lib.
Inefficiently rescan package lists for non
marked libraries.
conflicts force installation of package in the presence
of conflicts.
installed in update mode, reinstall an existing package
with the same signature.
kitchensink will install everything and the kitchen sink:
randomly reorder the list of packages to in-
stall, and proceed after weeding out conflicts.
libdepends library specifications may not be fulfilled.
noclosure do not compute the closure of dependencies to
figure out which packages to update when using
-u.
nonroot install even if not running as root.
pkgpath with -u, do not check the pkgpath matches if
only one candidate is found.
scripts external scripts may fail.
update unsafe update: old packing-list will run
scripts that may fail.
updatedepends force update even if forward dependencies no
longer match.
-I If scripts exist for a given package, do not execute them.
-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, pack-
ages can be created using a different localbase (see
pkg_create(1)), and those packages can only be installed by us-
ing the same localbase. See bsd.port.mk(5) for a description of
LOCALBASE.
-n Don't actually install a package, just report the steps that
would be taken if it was.
-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 instal-
lation stops at @endfake marker.
-q Replace package quickly; do not bother checking MD5s before re-
moving files.
-r Replace existing packages. pkg_add will try to take every pre-
caution to make sure the replacement can proceed before removing
the old package and adding the new one, and it should also han-
dle 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 -F update to force the
replacement); pkg_add will also refuse to replace packages when
the dependencies don't quite match (use -F updatedepends to
force the replacement).
-u Update the given 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.
-x Disable progress-meter.
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.
Technical details
pkg_add extracts each package's ``packing information'' (the packing
list, description, and installation/deinstallation scripts) into a spe-
cial 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, installation is terminated.
2. A check is made to determine if the package conflicts (from @pkgcfl
directives; see pkg_create(1)) with a package already recorded as
installed. If it is, 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 de-
pendencies are not currently fulfilled, an attempt is made to find a
package that meets them and install it, looking first 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 a require script (see pkg_create(1)), it is
executed with the following arguments:
pkg-name The name of the package being installed
INSTALL Keyword denoting to the script that it is to run an
installation requirements check (the keyword is useful
only to scripts which serve multiple functions).
If the require script exits with a non-zero status code, the instal-
lation is terminated.
7. If the package contains an install script, 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 ac-
tions needed before the package is installed.
If the install script exits with a non-zero status code, the instal-
lation is terminated.
8. The packing list is used as a guide for extracting files from the
package into their final locations.
9. If an install script exists for the package, 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 ac-
tions needed after the package has been installed.
10. 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).
11. 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 in-
stalled. If its signature is identical to that of the new package,
no replacement is performed (unless -F installed is specified).
2. A check is made to determine what old package the new package should
replace, using conflicts.
3. A check is made to determine whether the old package will be deleted
without issue, and whether the new package will install correctly.
This includes refusing to run any code (unless -F update), and veri-
fying that the new package still matches dependencies (unless -F up-
datedepends).
4. Shared libraries deserve special treatment: each shared library from
the old package that does no longer exist in the new package, but
that is required from a wantlib of another package is kept along in
a stub package named .libs-<pkgname>.
5. The new package is extracted to the filesystem, using temporary
filenames of the form pkg.XXXXXXX since the old package is still
there. The packing-list is amended to record these names as @temp
annotations, in cases the installation fails.
6. The old package is deleted as usual, except that some packages may
still depend on it.
7. The new package is installed as usual, except that the files are al-
ready present and only need to be renamed.
8. Dependencies from the old package are adjusted to point to the new
package.
To update packages in -u mode, pkg_add performs the following steps.
1. Packages to update are checked for dependencies, and their dependen-
cies are marked for update as well, unless -F noclosure.
2. 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.
3. Some minimal version matching occurs: out of all p* variations of a
given package, only the most recent package is kept (unless -F al-
lversions is given). Note that pkg_add does not try to compare ver-
sions in a smarter way, 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 modi-
fiers), 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 need-
ed.
6. If several candidates are left, pkg_add will ask the user in inter-
active mode, and not perform the update in non-interactive mode.
7. Once a suitable update candidate has been found for every package,
pkg_add proceeds to print out the list of new packages, and then
performs the update.
8. If some updates can't be solved, pkg_add stops before the update,
unless -F alwaysupdate.
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 under-
stands ${FETCH_CMD} -o - url.
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, ending in a slash. URL schemes such as FTP,
HTTP, 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 ex-
tracted, instead of /var/tmp.
SEE ALSO
ftp(1), pkg_create(1), pkg_delete(1), pkg_info(1), bsd.port.mk(5),
package(5)
AUTHORS
Jordan Hubbard
Initial design.
Marc Espie
Complete rewrite.
CAVEATS
Package extraction does need a temporary area that can hold executable
scripts.
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 con-
tains executable scripts.
OpenBSD 4.1 November 25, 1994 6