NAME
pkg_add
—
install or update software
packages
SYNOPSIS
pkg_add |
[-acIimnqrsUuVvxz ]
[-A arch]
[-B pkg-destdir]
[-D name[=value]]
[-L localbase]
[-l file]
[-P type]
[pkg-name ...] |
DESCRIPTION
The pkg_add
command is used to install or
update packages(7)
created from the ports(7)
tree.
pkg_add
.By default, pkg_add
rejects unsigned
packages unless they come from a trusted source
(TRUSTED_PKG_PATH
) or option
-D
unsigned
is used.
If a package is signed:
pkg_add
checks that its signature is valid and that the signature was emitted by a valid signing key, as stored in /etc/signify/*-pkg.pub,pkg_add
verifies that the compressed package data matches the signature, before it decompresses and unpacks files (see signify(1) in-z
mode).
pkg_add
can be used to
- Install new packages. This is the normal mode. The pkg-name ... specified on the command line are new package names to install.
- Update installed packages, using option
-u
. Optional pkg-name ... may be specified on the command line, as names of packages already installed on the machine, to be updated to new versions along with their dependencies. If no name is specified, all the packages will be updated. - Install new packages in a hurry, updating their dependencies first, using
option
-U
. The pkg-name ... specified on the command line are new packages that may require updating dependencies first. It is recommended to keep all packages in-synch with-u
whenever possible, but-U
can be much faster. - Replace existing packages with explicit other versions, using option
-r
. The pkg-name ... specified on the command line are new packages that should replace already installed packages, with other versions or flavors.
pkg_add
relies on the file system
information being consistent. In case of a system crash,
/var/db/pkg may become corrupted. Use
pkg_check(8) to repair
things.
Details of packing-list internals are documented in pkg_create(1).
pkg_add
will
syslog(3) installations and
updates by default.
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. If the given package
names are not found in the current working directory,
pkg_add
will search for them in each directory
(local or remote) named by the TRUSTED_PKG_PATH
environment variable, then the PKG_PATH
environment
variable. The special url ‘installpath’ refers to the contents
of installurl(5). If
neither TRUSTED_PKG_PATH
nor
PKG_PATH
are defined,
pkg_add
will use ‘./:installpath’ as a
default. 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.
pkg_add
may ask questions in interactive
mode, or error out otherwise. Interactive mode is the default on a tty, see
options -I/i
.
For instance ‘pkg_add
vim’ is ambiguous as it matches
vim-*-no_x11, vim-*-gtk3, and a
few other flavors.
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
vim--no_x11’ (matches only the no_x11 flavor)
or ‘pkg_add
vim--gtk3’ (matches only the gtk3 flavor).
There is also an ambiguity related to ports with multiple
branches. For instance ‘pkg_add
python’ is ambiguous, as there are several
versions of python in the ports tree. So is
‘pkg_add
postfix’. The special form
‘pkgname%branch’
can be used to restrict matches to a branch matching the
pkgpath(7).
The above ambiguities can be resolved using
‘pkg_add
postfix%stable’ and
‘pkg_add
python%3.9’,
respectively.
All paths recognize certain special sequences, which are expanded as follows:
- %a
- The package architecture as returned by arch(1)
-s
. - %v
- The operating system version in the format “digit dot digit”.
- %c
- Expands to the string "snapshots" when running a -current or
-beta kernel, or if the command line option
-D
snap
|-D
snapshot
is specified. Otherwise, %c expands to %v, which selects a release version. - %m
- The full mirror path, "/pub/OpenBSD/%c/packages/%a/".
If the resulting path contains "%c/packages" and %c is not "snapshots", then a second directory is also searched, which is constructed by replacing "packages" with "packages-stable".
The following examples are valid:
pkg_add -v http://ftp.openbsd.org/%m/rsync-- pkg_add -v http://ftp.openbsd.org/%m/m4 pkg_add -v scp://login@host/usr/ports/packages/%a/all/tcl%8.5
If the environment variable PKG_CACHE
is
set to a directory name, every package retrieved from a distant location
will also be copied here.
If the environment variable
DEBUG_PKG_CACHE
is set to a directory name, debug
packages matching installed/updated packages will be downloaded to that
directory (this is to avoid ‘shearing’, as later on, you might
wish to debug software, but the snapshots will have moved on and the debug
packages no longer match your installation). This only applies to debug
packages that are not currently installed/updated.
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.
Warning:
Since pkg_add
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.
-aa
- Force already installed packages to be tagged as installed automatically.
-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
in the packing-list.
@extra file
-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.
checksum
- Verify checksums before deleting or tying old files.
dontmerge
- By default, if dependencies are too strict,
pkg_add
will merge updates together to make sure everything stays in sync.-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 update signature.
nonroot
- Install even if not running as root.
repair
- Attempt to repair installed packages with missing registration data.
scripts
- External scripts may fail.
SIGNER
- List of trusted signers, separated by commas. Corresponds to list of public keys under /etc/signify we want to trust. Defaults to any key matching ‘*pkg’.
snap
|snapshot
- Force ‘%c’ and ‘%m’ to expand to ‘snapshots’, even on a release kernel.
unsigned
- Allow the installation of unsigned packages without warnings/errors.
But see
TRUSTED_PKG_PATH
, which is more discriminating. updatedepends
- Force update even if dependencies no longer match.
-I
- Force non-interactive mode. Default is to be interactive when run from a tty.
-i
- Force interactive mode, even if not run from a tty.
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, to reproduce an installation
from machine to machine, use
pkg_info -mz >installed_list
on the source machine andpkg_add -l installed_list
on the destination machine. -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
ftp- Check that package can be distributed on ftp.
-qq
- Do not bother with checksums for configuration files.
-r
- Replace existing packages.
-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 onPKG_PATH
to figure out the new package names. -V
- Displays the number of packages done/total number of packages.
-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
will 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
pkg_add
differentiates between packages
specified on the command line, and packages installed automatically because
of inter-dependencies: the first kind will be tagged as ‘installed
manually’. The -a
option is used internally
by the ports(7)
infrastructure and dpb(1) to
handle dependencies.
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
pkg_add
deals with
‘updatesets’ internally. An updateset is a collection of old
package(s) to delete, and new package(s) to install, as an atomic operation.
Under normal circumstances, an updateset contains at most one old package
and one new package, but some situations may require
pkg_add
to perform several installations/deletions
at once.
For each new package in an updateset,
pkg_add
extracts the package's “packing
information” (the packing-list and description mostly) into a special
staging directory under /tmp (or
PKG_TMPDIR
if set) and then runs through the
following sequence to fully extract the contents of the package:
- A check is made to determine if the package is already recorded as installed. If it is, the installation is terminated.
- 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. - For packages tagged with architecture constraints,
pkg_add
verifies that the current machine architecture agrees with the constraints. - 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 topkg_add
; if no adequate package can be found and installed, the installation is terminated. pkg_add
checks for collisions with installed file names, read-only file systems, and enough space to store files.- The packing-list is used as a guide for extracting files from the package into their final locations.
- After installation is complete, a copy of all package files such as the
packing-list, extra messages, or 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). - 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.
- A check is made to determine if a similar package is already installed. If
so, its full update signature is computed, which contains all the
necessary dependency information along with the actual package version. If
that signature is identical to that of the new package, no replacement is
performed (unless
-D
installed
is specified). - 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 updates to those packages. - 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 verifying that the new package still matches dependencies (unless
-D
updatedepends
). - 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>.
pkg_add
uses sha256 checksums to avoid extracting too much: if a file from an old package didn't change, it will be reused verbatim, and the extraction will often finish early.- The new packages are extracted to the filesystem, using temporary filenames of the form pkg.XXXXXXX if necessary to avoid conflicts with the old packages. The packing-list is amended to record these names as @temp annotations, in cases the installation fails.
- 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. - 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. - 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.
- 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. 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.- Version matching occurs: unless
-D
downgrade
, only packages with newer versions will be considered as update candidates. Note that version matching is costly, thusPKG_PATH
should point to a snapshot of packages for a given version of OpenBSD, similar to the organization on the FTP sites. - Candidates are then matched according to their pkgpaths (see pkgpath(7) and pkg_create(1)) in order to weed out similar packages with distinct options.
- The update signature of the candidate is compared to the signature of the already installed package: identical signatures mean no update needed.
- If several candidates are left,
pkg_add
will ask the user in interactive mode, and not perform the update in non-interactive mode. - 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
DEBUG_PKG_CACHE
- If set, debug packages matching installed/updated packages will be downloaded to that directory as well.
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
. PKG_CACHE
- If set, any package retrieved from a distant location will be copied to that directory as well.
PKG_CHECKSUM
- If set, verify files checksums during deletion, exactly like
-D
checksum
. PKG_DBDIR
- Where to register packages instead of /var/db/pkg.
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 (‘./
’). Special sequences ‘%a’, ‘%c’, ‘%m’, ‘%v’ will be expanded. PKG_TMPDIR
- Temporary area where package information files will be extracted, instead of /tmp.
TRUSTED_PKG_PATH
- Same semantics as
PKG_PATH
, but it is searched beforePKG_PATH
and waives any kind of signature checking.
FILES
- /etc/installurl
- default mirror server for package download
- /etc/signify/*-pkg.pub
- public keys for package verification with signify(1)
- /usr/local/
- default file system to install packages in
- /usr/local/share/doc/pkg-readmes/
- OpenBSD-specific information about individual packages
- /var/db/pkg/
- database of installed packages(7)
SEE ALSO
ftp(1), pkg_create(1), pkg_delete(1), pkg_info(1), OpenBSD::Intro(3p), bsd.port.mk(5), installurl(5), package(5), pkg_check(8)
AUTHORS
- Jordan Hubbard
- Initial design.
-
Marc Espie - Complete rewrite.