pkg_add man page on OpenBSD

Man page or keyword search:  
man Server   11362 pages
apropos Keyword Search (all sections)
Output format
OpenBSD logo
[printable version]

PKG_ADD(1)		   OpenBSD Reference Manual		    PKG_ADD(1)

     pkg_add - install software package distributions

     pkg_add [-acIimnqrsUuvxz] [-A arch] [-B pkg-destdir] [-D name[=value]]
	     [-L localbase] [-l file] [-P type] [-Q quick-destdir]
	     pkg-name [...]

     The pkg_add command is used to install packages created with the
     pkg_create(1) command.  Selected packages containing pre-compiled
     applications 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).

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

     If a package is digitally signed:

     o	 pkg_add checks that its packing-list is not corrupted and matches the
	 cryptographic signature stored within.

     o	 pkg_add verifies that the signature was emitted by a valid user
	 certificate, signed by one of the authorities in /etc/ssl/pkgca.pem

     o	 pkg_add verifies that each file matches its sha256 checksum right
	 after extraction, before doing anything with it.

     o	 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
     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, 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
	   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*.
	   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

     The options are as follows:

     -A arch  Assume arch as current machine architecture for any package

     -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

	      allversions      do not trim older p* variants of packages for
	      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.
	      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	      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,
	      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 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 >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.

     -P type  Check permissions for distribution, where type can be `cdrom' or

     -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

     -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

     -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

     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 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, 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

     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

     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

     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

     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

     5.	  The signature of the candidate is compared to the signature of the
	  already installed package: identical signatures mean no update

     6.	  If several candidates are left, pkg_add will ask the user in
	  interactive mode, and not perform the update in non-interactive

     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.

     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.

		  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

     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.

     ftp(1), pkg_create(1), pkg_delete(1), pkg_info(1), OpenBSD::Intro(3p),, package(5)

     Jordan Hubbard
	     Initial design.
     Marc Espie
	     Complete rewrite.

     Package extraction does need a temporary area that can hold executable

     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.

OpenBSD 4.9		       February 7, 2011			   OpenBSD 4.9

List of man pages available for OpenBSD

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
Vote for polarhome
Free Shell Accounts :: the biggest list on the net