pkg_add(1)

NAME

pkg_add - a utility for installing software package distri

butions

SYNOPSIS

pkg_add  [-vInfrRMSK]  [-t template] [-p prefix] [-P prefix]
[-C chrootdir]
        pkg-name [pkg-name ...]

DESCRIPTION

The pkg_add command is used to extract packages that have

been previously
created with the pkg_create(1) command.

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
package files.

You are advised to verify the competence and identity of

those who provide installable package files. For extra protection, use

the -M flag to
extract the package file, and inspect its contents and

scripts to ensure
it poses no danger to your system's integrity. Pay

particular attention
to any +INSTALL, +POST-INSTALL, +DEINSTALL, +POST-DEINSTALL,

+REQUIRE or
+MTREED_IRS files, and inspect the +CONTENTS file for @cwd,

@mode (check
for setuid), @dirrm, @exec, and @unexec directives, and/or

use the
pkg_info(1) command to examine the package file.

OPTIONS

The following command line arguments are supported:

pkg-name [pkg-name ...]

The named packages are installed. A package name of

- will cause
pkg_add to read from stdin. If the packages are not

found in the
current working directory, pkg_add will search them

in each
directory named by PKG_PATH.

-v Turn on verbose output.

-K Keep any downloaded package in PKGDIR if it is de

fined or in cur

rent directory by default.

-I If any installation scripts (pre-install or post-in

stall) exist

for a given package, do not execute them.

-n Do not actually install a package, just report the

steps that

would be taken if it was.

-R Do not record the installation of a package. This

means that you

cannot deinstall it later, so only use this option

if you know
what you are doing!

-r Use the remote fetching feature. This will deter

mine the appro

priate objformat and release and then fetch and in

stall the package.

-f Force installation to proceed even if prerequisite

packages are

not installed or the requirements script fails. Al

though pkg_add
will still try to find and auto-install missing pre

requisite
packages, a failure to find one will not be fatal.

-p prefix

Set prefix as the directory in which to extract

files from a
package. If a package has set its default directo

ry, it will be
overridden by this flag. Note that only the first

@cwd directive
will be replaced, since pkg_add has no way of know

ing which
directory settings are relative and which are abso

lute. It is
rare in any case to see more than one directory

transition made,
but when such does happen and you wish to have con

trol over *all*
directory transitions, then you may then wish to

look into the
use of MASTER and SLAVE modes (see the -M and -S op

tions). If the
-p flag appears after any -P flag on the command

line, it overrides it's effect, causing pkg_add not to use the

given prefix
recursively.

-P prefix

Does the same as the -p option, except that the giv

en prefix is
also used recursively for the dependency packages,

if any. If the
-P flag appears after any -p flag on the command

line, it overrides it's effect, causing pkg_add to use the given

prefix recursively.

-t template

Use template as the input to mktemp(3) when creating

a ``staging
area''. By default, this is the string

/var/tmp/instmp.XXXXXX,
but it may be necessary to override it in the situa

tion where
space in your /var/tmp directory is limited. Be

sure to leave
some number of `X' characters for mktemp(3) to fill

in with a
unique ID.

You can get a performance boost by setting the stag

ing area
template to reside on the same disk partition as

target directories for package file installation; often this is

/usr.

-M Run in MASTER mode. This is a very specialized mode

for running

pkg_add and is meant to be run in conjunction with

SLAVE

When run in this mode, pkg_add does no work beyond

extracting the
package into a temporary staging area (see the -t

option), reading in the packing list, and then dumping it (pref

aced by the
current staging area) to stdout where it may be fil

tered by a
program such as sed(1). When used in conjunction

with SLAVE
mode, it allows you to make radical changes to the

package structure before acting on its contents.

-S Run in SLAVE mode. This is a very specialized mode

for running

pkg_add and is meant to be run in conjunction with

MASTER

When run in this mode, pkg_add expects the release

contents to be
already extracted and waiting in the staging area,

the location
of which is read as a string from stdin. The com

plete packing
list is also read from stdin, and the contents then

acted on as
normal.

-C chrootdir

Before doing any operations, chroot(2) to the

chrootdir directory
so that all package files, and the package database,

are
installed to chrootdir. Note that chrootdir needs

to be a fairly
complete file system, including everything normally

needed by
pkg_add to run. This flag was added to help support

operations
done by sysinstall(8) and is not expected to be use

ful for much
else. Be careful that chrootdir is properly config

ured and cannot be modified by normal users, versions of com

mands like
fetch(1) may be run inside chrootdir as a side ef

fect.

One or more pkg-name arguments may be specified, each being

either a file
containing the package (these usually end with a ``.tbz''

suffix) or a
URL pointing at a file available on an ftp site. Thus you

may extract
files directly from their anonymous ftp locations (e.g.

pkg_add
ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/pack

ages/shells/bash-1.14.7.tbz).
Note: If you wish to use passive mode ftp in such transfers,

set the
variable FTPP_ASSIVEM_ODE to some value in your environment.

Otherwise,
the more standard ACTIVE mode may be used. If pkg_add con

sistently fails
to fetch a package from a site known to work, it may be be

cause you have
a firewall that demands the usage of passive mode ftp.

TECHNICAL DETAILS

The pkg_add utility extracts each package's "packing list"

into a special
staging directory in /tmp (or $PKG_TMPDIR if set), parses

it, 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@conflicts directives, see pkg_create(1)) with an al

ready-installed
package. If it is, installation is terminated.

3. Scan all the package dependencies (from @pkgdep direc

tives, see
pkg_create(1)) are read from the packing list. If any

of these
required packages is not currently installed, an at

tempt is made to
find and install it; if the missing package cannot be

found or
installed, the installation is terminated.

4. Search for any @option directives which control how the

package is
added to the system. At the time of this writing, the

only currently implemented option is @option extract-in-place

which will
cause the package to be extracted directly into its

prefix directory
without moving through a staging area in /tmp.

5. If @option extract-in-place is enabled, the package is

now extracteddirectly into its final location, otherwise it is ex

tracted into the
staging area.

6. If the package contains a require file (see pkg_cre

ate(1)), then
execute it with the following arguments:
pkg-name INSTALL

where pkg-name is the name of the package in question

and the
INSTALL keyword denotes this as an installation re

quirements check
(useful if you want to have one script serving multiple

functions).

7. If a pre-install script exists for the package, it is

then executed
with the following arguments:
script pkg-name PRE-INSTALL

where pkg-name is the name of the package in question

and
PRE-INSTALL is a keyword denoting this as the prein

stallation phase.

Note: The PRE-INSTALL keyword will not appear if sepa

rate scripts
for pre-install and post-install are given during pack

age creation
time (using the -i and -I flags to pkg_create(1)).

8. If @option extract-in-place is not used, then the pack

ing list (thisis the +CONTENTS file) is now used as a guide for mov

ing (or copying, as necessary) files from the staging area into

their final
locations.

9. If the package contains an mtreefile file (see pkg_cre

ate(1)), then
mtree is invoked as:
mtree -u -f mtreefile -d -e -p prefix

where prefix is either the prefix specified with the -p

or -P flag
or, if neither flag was specified, the name of the

first directory
named by a @cwd directive within this package.

10. If a post-install script exists for the package, it is

then executed
as
script pkg-name POST-INSTALL

where pkg-name is the name of the package in question

and
POST-INSTALL is a keyword denoting this as the post-in

stallation
phase.

Note: The POST-INSTALL keyword will not appear if sepa

rate scripts
for pre-install and post-install are given during pack

age creation
time (using the -i and -I flags to pkg_create(1)).

Reasoning behind passing keywords such as POST-INSTALL

and
PRE-INSTALL is that this allows you to write a single

install script
that does both ``before and after'' actions. But, sep

arating the
functionality is more advantageous and easier from a

maintenance
viewpoint.

11. After installation is complete, a copy of the packing

list,
deinstall script, description, and display files are

copied into
/var/db/pkg/<pkg-name> for subsequent possible use by

pkg_delete(1).
Any package dependencies are recorded in the other

packages'
/var/db/pkg/<other-pkg>/+REQUIREDB_Y file (if the envi

ronment variable PKG_DBDIR is set, this overrides the /var/db/pkg/

path shown
above).

12. Finally, the staging area is deleted and the program

terminates.

All the scripts are called with the environment variable

PKG_PREFIX set
to the installation prefix (see the -p and -P options

above). This
allows a package author to write a script that reliably per

forms some
action on the directory where the package is installed, even

if the user
might change it with the -p or -P flags to pkg_add.

ENVIRONMENT

The value of the PKG_PATH is used if a given package cannot

be found.
The environment variable should be a series of entries sepa

rated by
colons. Each entry consists of a directory name. The cur

rent directory
may be indicated implicitly by an empty directory name, or

explicitly by
a single period.

The environment variable PKG_DBDIR specifies an alternative

location for
the installed package database, default location is

/var/db/pkg.

The environment variables PKG_TMPDIR and TMPDIR, in that or

der, are taken
to name temporary directories where pkg_add will attempt to

create its
staging area in. If these variables are not present or if

the directories named lack sufficient space, then pkg_add will use the

first of
/var/tmp, /tmp or /usr/tmp with sufficient space.

The environment variable PACKAGEROOT specifies an alternate

location for
pkg_add to fetch from. The fetch URL is built using this

environment
variable and the automatic directory logic that pkg_add uses

when the -r
option is invoked. An example setting would be

"ftp://ftp3.FreeBSD.org".

The environment variable PACKAGESITE specifies an alternate

location for
pkg_add to fetch from. This variable subverts the automatic

directory
logic that pkg_add uses when the -r option is invoked. Thus

it should be
a complete URL to the remote package file(s).

The environment variable PKGDIR specifies an alternative lo

cation to save
downloaded packages to when -K option is used.

FILES

/var/tmp Temporary directory for creating the staging

area, if envi
ronmental variables PKG_TMPDIR or TMPDIR do not

point to a
suitable directory.

/tmp Next choice if /var/tmp does not exist or has

insufficient
space.

/usr/tmp Last choice if /var/tmp and /tmp are not suit

able for creat
ing the staging area.

/var/db/pkg Default location of the installed package

database.

SEE ALSO

pkg_create(1), pkg_delete(1), pkg_info(1), pkg_version(1),

mktemp(3),
sysconf(3), mtree(8)

AUTHORS

Jordan Hubbard

CONTRIBUTORS

John Kohl <jtk@rational.com>

BUGS

Hard links between files in a distribution are only pre

served if either
(1) the staging area is on the same file system as the tar

get directory
of all the links to the file, or (2) all the links to the

file are bracketed by @cwd directives in the contents file, and the link

names are
extracted with a single tar command (not split between invo

cations due to
exec argument-space limitations--this depends on the value

returned by
sysconfS_A_RGM_AX)).

Sure to be others.

BSD January 16, 2006

BSD