.\"	$OpenBSD: pkg_add.1,v 1.27 2004/12/09 18:58:25 espie Exp $
.\"
.\" FreeBSD install - a package for the installation and maintenance
.\" of non-core utilities.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" Jordan K. Hubbard
.\"
.\"
.\"     @(#)pkg_add.1
.\"
.Dd November 25, 1994
.Dt PKG_ADD 1
.Os
.Sh NAME
.Nm pkg_add
.Nd install software package distributions
.Sh SYNOPSIS
.Nm pkg_add
.Op Fl acInqrvx
.Op Fl A Ar arch
.Op Fl B Ar pkg-destdir
.Op Fl f Ar keys
.Op Fl L Ar localbase
.Op Fl P Ar type
.Op Fl Q Ar quick-destdir
.Ar pkg-name Op Ar ...
.Sh DESCRIPTION
The
.Nm
command is used to install packages created
with the
.Xr pkg_create 1
command.
Selected packages containing pre-compiled applications from the
.Pa /usr/ports
tree can be found on the
.Ox
FTP site or on the official
.Ox
CD.
.Bd -filled -offset indent
.Em Note :
System distribution files, e.g., base28.tgz, comp28.tgz, are
.Em not
packages and may not be installed using
.Nm .
.Ed
.Pp
Each package name may be specified as a filename (which normally consists of the
package name itself plus the
.Dq .tgz
suffix) or an URL referring to FTP, HTTP, or SCP locations.
For example, the following is valid:
.Pp
.Li pkg_add -v ftp://ftp.openbsd.org/pub/OpenBSD/2.7/packages/i386/m4-1.4.tgz
.Pp
If the given package names are not found in the current working directory,
.Nm
will search for them in each directory named by the
.Ev PKG_PATH
environment variable.
Specifying
.Ql -
as a package name causes
.Nm
to read from the standard input.
.Pp
Some packages may depend on other packages.
When resolving dependencies
.Nm
will first look at already installed packages, then match
dependencies with the list of packages left to install, then
install default packages that satisfy the dependencies.
.Pp
Alternatively, it is possible to add packages interactively from within the
.Xr ftp 1
client,
in which case setting
.Ev PKG_PATH
correctly will be necessary for any dependency to be found out and retrieved
the same way.
For example, the following works:
.Bd -literal -offset indent
$ 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 -"
.Ed
.Pp
.Sy Warning:
Since the
.Nm
command may execute scripts or programs contained within a package file,
your system may be susceptible to
.Dq trojan horses
or other subtle attacks from miscreants who create dangerous packages.
Be sure the specified package(s) are from trusted sources.
.Pp
The options are as follows:
.Bl -tag -width keyword
.It Fl A Ar arch
Assume
.Ar arch
as current machine architecture for any package tests.
.It Fl a
Automated package installation; do not record packages as installed manually.
.It Fl B Ar pkg-destdir
Set
.Ar pkg-destdir
as the prefix to prepend to any object extracted from the package.
.It Fl c
While replacing packages, delete extra configuration file in the old package,
mentioned as
.Dl @extra file
in the packing-list.
.It Fl f Ar keys
Force installation of the package.
.Ar keys
is a comma-separated list of keywords that state what failsafes
should be waived.
These include:
.Pp
.Bl -tag -width "updatedependsXX" -compact
.It Ar arch
architecture recorded in package may not match.
.It Ar conflicts
package may conflict with other packages.
.It Ar installed
in update mode, reinstall an existing package with the same signature.
.It Ar libdepends
library specifications may not be fulfilled.
.It Ar nonroot
install even if not running as root.
.It Ar scripts
external scripts may fail.
.It Ar update
unsafe update: old packing-list will run scripts that may fail.
.It Ar updatedepends
force update even if forward dependencies no longer match.
.El
.It Fl I
If scripts exist for a given package, do not execute them.
.It Fl L Ar localbase
Install a package under
.Ar localbase .
By default,
.Ar localbase
equals
.Pa /usr/local ,
and specifying it is not necessary.
However, packages can be created using a different
.Ar localbase
.Po
see
.Xr pkg_create 1
.Pc ,
and those packages can only be installed by using the same
.Ar localbase .
See
.Xr bsd.port.mk 5
for a description of
.Ev LOCALBASE .
.It Fl n
Don't actually install a package, just report the steps that
would be taken if it was.
.It Fl P Ar type
Check permissions for distribution, where
.Ar type
can be
.Sq cdrom
or
.Sq ftp .
.It Fl Q Ar quick-destdir
Quick and dirty installation under
.Ar quick-destdir .
Contrary to
.Fl B
.Ar pkg-destdir ,
symbolic links are resolved, and package installation stops at
.Cm @endfake
marker.
.It Fl q
Replace package quickly; do not bother checking MD5s before removing files.
.It Fl r
Allow replacing existing packages.
This is an experimental option for now:
the code will try to take every precaution to make sure the update can
proceed before removing the old package and adding the new one, and it
should also handle shared libraries correctly.
But this functionality has seen very little testing yet, and since it is
rather powerful, it can break a system in a thorough way.
.It Fl v
Turn on verbose output.
Several
.Fl v
turn on more verbose output.
.It Fl x
Disable progress-meter.
.El
.Pp
By default, when adding packages via FTP, the
.Xr ftp 1
program operates in
.Dq passive
mode.
If you wish to use active mode instead, set the
.Ev FTPMODE
environment variable to
.Dq active .
If
.Nm
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
.Nm
will try active mode FTP if the server refuses a passive mode
connection.
.Ss Technical details
.Nm
extracts each package's
.Dq packing information
(the packing list, description, and installation/deinstallation scripts)
into a special staging directory in
.Pa /var/tmp
(or
.Ev PKG_TMPDIR
if set \- see
.Sx CAVEATS ,
below)
and then runs through the following sequence to fully extract the contents
of the package:
.Bl -enum
.It
A check is made to determine if the package is already recorded as installed.
If it is,
installation is terminated.
.It
A check is made to determine if the package conflicts (from
.Cm @pkgcfl
directives; see
.Xr pkg_create 1 )
with a package already recorded as installed.
If it is, installation is terminated.
.It
For packages tagged with architecture constraints,
.Nm
verifies that the current machine architecture agrees with the constraints.
.It
All package dependencies (from
.Cm @pkgdep ,
.Cm @libdepend ,
and
.Cm @newdepend
directives; see
.Xr 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 list of packages to install passed to
.Nm ;
if no adequate package can be found and installed,
the installation is terminated.
.It
.Nm
checks for collisions with installed file names, read-only file systems,
and enough space to store files.
.It
If the package contains a
.Ar require
script (see
.Xr pkg_create 1 ) ,
it is executed with the following arguments:
.Bl -tag -width indentindent
.It Ar pkg-name
The name of the package being installed
.It Cm 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).
.El
.Pp
If the
.Ar require
script exits with a non-zero status code, the installation is terminated.
.It
If the package contains an
.Ar install
script, it is executed with the following arguments:
.Bl -tag -width indentindent
.It Ar pkg-name
The name of the package being installed.
.It Cm PRE-INSTALL
Keyword denoting that the script is to perform any actions needed before
the package is installed.
.El
.Pp
If the
.Ar install
script exits with a non-zero status code, the installation is terminated.
.It
The packing list is used as a guide for extracting
files from the package into their final locations.
.It
If an
.Ar install
script exists for the package, it is executed with the following arguments:
.Bl -tag -width indentindent
.It Ar pkg_name
The name of the package being installed.
.It Cm POST-INSTALL
Keyword denoting that the script is to perform any actions needed
after the package has been installed.
.El
.It
After installation is complete, a copy of all package files
such as the packing-list, the
.Ar install
and
.Ar deinstall
scripts, the description file is made into
.Pa /var/db/pkg/<pkg-name>
for subsequent possible use by
.Xr pkg_delete 1
and
.Xr pkg_info 1 .
Any package dependencies are recorded in the other packages'
.Pa /var/db/pkg/<other-pkg>/+REQUIRED_BY
file
(if the environment variable
.Ev PKG_DBDIR
is set, this overrides the
.Pa /var/db/pkg/
path shown above).
.It
Finally, the staging area is deleted and the program terminates.
.El
.Pp
Note that it is safe to interrupt
.Nm pkg_add
through
.Dv SIGINT ,
as it will safely record an interrupted install as
.Pa borked.n .
.Sh ENVIRONMENT
.Bl -tag -width PKG_DESTDIR
.It Ev FTPMODE
Specifies whether
.Xr ftp 1
should operate in
.Dq active
or
.Dq passive
mode.
The default is
.Dq passive .
.It Ev PKG_DBDIR
Where to register packages instead of
.Pa /var/db/pkg .
.It Ev PKG_DESTDIR
Value for
.Ar pkg-destdir ,
if no
.Fl B
option is specified;
value passed to any
.Cm INSTALL
or
.Cm REQUIRE
script invoked from the package.
.It Ev PKG_PATH
If a given package name cannot be found,
the directories named by
.Ev PKG_PATH
are searched.
It should contain a series of entries separated by colons.
Each entry consists of a directory name.
The current directory may be indicated
implicitly by an empty directory name, or explicitly by a single
period
.Pq Ql \&. .
.It Ev PKG_TMPDIR
Temporary area where package information files will be extracted, instead of
.Pa /var/tmp .
.El
.Sh SEE ALSO
.Xr ftp 1 ,
.Xr pkg_create 1 ,
.Xr pkg_delete 1 ,
.Xr pkg_info 1 ,
.Xr bsd.port.mk 5
.Sh AUTHORS
.Bl -tag -width indent -compact
.It "Jordan Hubbard"
Initial design.
.It "Marc Espie"
Complete rewrite.
.El
.Sh CAVEATS
Package extraction does need a temporary area that
can hold executable scripts.
.Pp
.Nm
looks through
.Ev ${PKG_TMPDIR} ,
.Ev ${TMPDIR} ,
.Pa /var/tmp ,
.Pa /tmp ,
and
.Pa /usr/tmp
for such an area, in sequence.
.Pp
If
.Ev ${TMPDIR}
and
.Pa /var/tmp
are mounted noexec, you must currently set
.Ev PKG_TMPDIR
to a suitable area, as
.Nm
does not check for noexec status except by failing to run installation
scripts.
.Sh BUGS
The
.Fl r
option has not seen wide-testing yet and is almost certainly full of bugs.
In particular, failure modes are untested, and a large number of code paths
have not seen actual use yet.
This option only handles atomic updates of single packages, there is no code
to replace multiple packages with another set of equivalent multiple packages.
For instance, since this option will often replace a package with
a newer package by creating an extra stub package for older shared libraries,
reversing the effect of pkg_add -r without wiping out most installed packages
will be impossible.