.\"	$OpenBSD: pkg_add.1,v 1.13 2004/03/07 19:29:08 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 Inv
.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
.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, etc., are
.Em not
packages and may not be installed using
.Nm pkg_add .
.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
.Ic 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 ftp 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
	$ 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 v
Turn on verbose output.
.It Fl I
If an installation script exists for a given package, do not execute it.
.It Fl n
Don't actually install a package, just report the steps that
would be taken if it was.
.It Fl A Ar arch
Assume
.Ar arch
as current machine architecture for any package tests.
.It Fl B Ar pkg-destdir
Set
.Ar pkg-destdir
as the prefix to prepend to any object extracted from the package.
.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:
.Bl -tag -width keyword
.It Ar arch
architecture recorded in package may not match.
.It Ar conflicts
package may conflict with other packages.
.It Ar installed
reinstall an existing package.
.It Ar libdepends
library specifications may not be fullfilled.
.It Ar nonroot
install even if not running as root.
.It Ar scripts
install scripts may fail.
.El
.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 P Ar type
Check permissions for distribution, where
.Ar type
can be
.Sq cdrom
or
.Sq ftp .
.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
.Qq 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 CAVEATS section)
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 an already recorded as installed package.
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 fullfilled,
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 the packing list,
.Ar deinstall
script, description, and display files are copied into
.Pa /var/db/pkg/<pkg-name>
for subsequent possible use by
.Xr pkg_delete 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 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_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_TMPDIR
Temporary area where package information files will be extracted, instead of
.Pa /var/tmp .
.El
.Sh SEE ALSO
.Xr pkg_create 1 ,
.Xr pkg_delete 1 ,
.Xr pkg_info 1 ,
.Xr mkdtemp 3 ,
.Xr sysconf 3 ,
.Xr mtree 8
.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 ,
.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.