604 lines
14 KiB
Groff
604 lines
14 KiB
Groff
.\"
|
|
.\" FreeBSD install - a package for the installation and maintainance
|
|
.\" 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
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd November 29, 2007
|
|
.Dt PKG_ADD 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm pkg_add
|
|
.Nd a utility for installing software package distributions
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl viInfFrRMSK
|
|
.Op Fl t Ar template
|
|
.Op Fl p Ar prefix
|
|
.Op Fl P Ar prefix
|
|
.Op Fl C Ar chrootdir
|
|
.Ar pkg-name Op Ar pkg-name ...
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
command is used to extract packages that have been previously created
|
|
with the
|
|
.Xr pkg_create 1
|
|
command.
|
|
.Sh WARNING
|
|
.Bf -emphasis
|
|
Since the
|
|
.Nm
|
|
command may execute scripts or programs contained within a package file,
|
|
your system may be susceptible to
|
|
.Dq Em trojan horses
|
|
or other subtle
|
|
attacks from miscreants who create dangerous package files.
|
|
.Pp
|
|
You are advised to verify the competence and identity of those who
|
|
provide installable package files.
|
|
For extra protection, use the
|
|
.Fl 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 +MTREE_DIRS files, and inspect the +CONTENTS file for
|
|
.Cm @cwd ,
|
|
.Cm @mode
|
|
(check for setuid),
|
|
.Cm @dirrm ,
|
|
.Cm @exec ,
|
|
and
|
|
.Cm @unexec
|
|
directives, and/or use the
|
|
.Xr pkg_info 1
|
|
command to examine the package file.
|
|
.Ef
|
|
.Sh OPTIONS
|
|
The following command line arguments are supported:
|
|
.Bl -tag -width indent
|
|
.It Ar pkg-name Op Ar pkg-name ...
|
|
The named packages are installed.
|
|
A package name of
|
|
.Fl
|
|
will cause
|
|
.Nm
|
|
to read from stdin.
|
|
If the packages are not found in the current
|
|
working directory,
|
|
.Nm
|
|
will search them in each directory named by
|
|
.Ev PKG_PATH .
|
|
.It Fl v
|
|
Turn on verbose output.
|
|
.It Fl K
|
|
Keep any downloaded package in
|
|
.Ev PKGDIR
|
|
if it is defined or in current directory by default.
|
|
.It Fl i
|
|
Install the package without fetching and installing
|
|
dependencies.
|
|
.It Fl I
|
|
If any installation scripts (pre-install or post-install) exist for a given
|
|
package, do not execute them.
|
|
.It Fl n
|
|
Do not actually install a package, just report the steps that
|
|
would be taken if it was.
|
|
.It Fl 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!
|
|
.It Fl r
|
|
Use the remote fetching feature.
|
|
This will determine the appropriate
|
|
objformat and release and then fetch and install the package.
|
|
.It Fl f
|
|
Force installation to proceed even if prerequisite packages are not
|
|
installed or the requirements script fails.
|
|
Although
|
|
.Nm
|
|
will still try to find and auto-install missing prerequisite packages,
|
|
a failure to find one will not be fatal.
|
|
.It Fl F
|
|
Already installed packages are not an error.
|
|
.It Fl p Ar prefix
|
|
Set
|
|
.Ar prefix
|
|
as the directory in which to extract files from a package.
|
|
If a package has set its default directory, it will be overridden
|
|
by this flag.
|
|
Note that only the first
|
|
.Cm @cwd
|
|
directive will be replaced, since
|
|
.Nm
|
|
has no way of knowing which directory settings are relative and
|
|
which are absolute.
|
|
It is rare in any case to see more than one
|
|
directory transition made, but when such does happen and you wish
|
|
to have control over *all* directory transitions, then you
|
|
may then wish to look into the use of
|
|
.Cm MASTER
|
|
and
|
|
.Cm SLAVE
|
|
modes (see the
|
|
.Fl M
|
|
and
|
|
.Fl S
|
|
options).
|
|
If the
|
|
.Fl p
|
|
flag appears after any
|
|
.Fl P
|
|
flag on the command line, it overrides its effect, causing
|
|
.Nm
|
|
not to use the given
|
|
.Ar prefix
|
|
recursively.
|
|
.It Fl P Ar prefix
|
|
Does the same as the
|
|
.Fl p
|
|
option, except that the given
|
|
.Ar prefix
|
|
is also used recursively for the dependency packages, if any.
|
|
If the
|
|
.Fl P
|
|
flag appears after any
|
|
.Fl p
|
|
flag on the command line, it overrides its effect, causing
|
|
.Nm
|
|
to use the given
|
|
.Ar prefix
|
|
recursively.
|
|
.It Fl t Ar template
|
|
Use
|
|
.Ar template
|
|
as the input to
|
|
.Xr mktemp 3
|
|
when creating a
|
|
.Dq staging area .
|
|
By default, this is the string
|
|
.Pa /var/tmp/instmp.XXXXXX ,
|
|
but it may be necessary to override it in the situation where
|
|
space in your
|
|
.Pa /var/tmp
|
|
directory is limited.
|
|
Be sure to leave some number of `X' characters
|
|
for
|
|
.Xr mktemp 3
|
|
to fill in with a unique ID.
|
|
.Pp
|
|
You can get a performance boost by setting the staging area
|
|
.Ar template
|
|
to reside on the same disk partition as target directories for package
|
|
file installation; often this is
|
|
.Pa /usr .
|
|
.It Fl M
|
|
Run in
|
|
.Cm MASTER
|
|
mode.
|
|
This is a very specialized mode for running
|
|
.Nm
|
|
and is meant to be run in conjunction with
|
|
.Cm SLAVE
|
|
mode.
|
|
When run in this mode,
|
|
.Nm
|
|
does no work beyond extracting the package into a temporary staging
|
|
area (see the
|
|
.Fl t
|
|
option), reading in the packing list, and then dumping it (prefaced by
|
|
the current staging area) to stdout where it may be filtered by a
|
|
program such as
|
|
.Xr sed 1 .
|
|
When used in conjunction with
|
|
.Cm SLAVE
|
|
mode, it allows you to make radical changes to the package structure
|
|
before acting on its contents.
|
|
.It Fl S
|
|
Run in
|
|
.Cm SLAVE
|
|
mode.
|
|
This is a very specialized mode for running
|
|
.Nm
|
|
and is meant to be run in conjunction with
|
|
.Cm MASTER
|
|
mode.
|
|
When run in this mode,
|
|
.Nm
|
|
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 complete packing list is also read from stdin,
|
|
and the contents then acted on as normal.
|
|
.It Fl C Ar chrootdir
|
|
Before doing any operations,
|
|
.Xr chroot 2
|
|
to the
|
|
.Ar chrootdir
|
|
directory so that all package files, and the package database, are
|
|
installed to
|
|
.Ar chrootdir .
|
|
Note that
|
|
.Ar chrootdir
|
|
needs to be a fairly complete file system, including everything normally
|
|
needed by
|
|
.Nm
|
|
to run.
|
|
This flag was added to help support operations done by
|
|
.Xr sysinstall 8
|
|
and is not expected to be useful for much else.
|
|
Be careful that
|
|
.Ar chrootdir
|
|
is properly configured and cannot be modified by normal users,
|
|
versions of commands like
|
|
.Xr fetch 1
|
|
may be run inside
|
|
.Ar chrootdir
|
|
as a side effect.
|
|
.El
|
|
.Pp
|
|
One or more
|
|
.Ar pkg-name
|
|
arguments may be specified, each being either a file containing the
|
|
package (these usually end with a
|
|
.Dq .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.\&
|
|
.Nm
|
|
.Li ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/shells/bash-1.14.7.tbz ) .
|
|
Note: If you wish to use
|
|
.Bf -emphasis
|
|
passive mode
|
|
.Ef
|
|
ftp in such transfers, set
|
|
the variable
|
|
.Bf -emphasis
|
|
FTP_PASSIVE_MODE
|
|
.Ef
|
|
to some value in your environment.
|
|
Otherwise, the more standard
|
|
ACTIVE mode may be used.
|
|
If
|
|
.Nm
|
|
consistently fails to fetch a package from a site known to work,
|
|
it may be because you have a firewall that demands the usage of
|
|
.Bf -emphasis
|
|
passive mode
|
|
.Ef
|
|
ftp.
|
|
.Sh TECHNICAL DETAILS
|
|
The
|
|
.Nm
|
|
utility extracts each package's
|
|
.Dq "packing list"
|
|
into a special staging directory (see
|
|
.Sx ENVIRONMENT ) ,
|
|
parses it, 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
|
|
.Ic @conflicts
|
|
directives, see
|
|
.Xr pkg_create 1 )
|
|
with an already installed package.
|
|
If it is, installation is terminated.
|
|
.It
|
|
Scan all the package dependencies (from
|
|
.Ic @pkgdep
|
|
directives, see
|
|
.Xr pkg_create 1 )
|
|
are read from the packing list.
|
|
If any of these required packages is not currently installed,
|
|
an attempt is made to find and install it;
|
|
if the missing package cannot be found or installed,
|
|
the installation is terminated.
|
|
.It
|
|
Search for any
|
|
.Ic @option
|
|
directives which control how the package is added to the system.
|
|
At the time of this writing, the only currently implemented option is
|
|
.Ic @option Cm extract-in-place
|
|
which will cause the package to be extracted directly into its
|
|
prefix directory without moving through a staging area.
|
|
.It
|
|
If
|
|
.Ic @option Cm extract-in-place
|
|
is enabled, the package is now extracted directly into its
|
|
final location, otherwise it is extracted into the staging area.
|
|
.It
|
|
If a requirements script
|
|
.Pa +REQUIRE
|
|
exists for the package (see the
|
|
.Fl r
|
|
flag of
|
|
.Xr pkg_create 1 ) ,
|
|
then execute it with the following arguments:
|
|
.Pp
|
|
.D1 Ar pkg-name Li INSTALL
|
|
.Pp
|
|
where
|
|
.Ar pkg-name
|
|
is the name of the package in question and the
|
|
.Dq Li INSTALL
|
|
keyword denotes this as an installation requirements check (useful if
|
|
you want to have one script serving multiple functions).
|
|
.It
|
|
If a pre-install script
|
|
.Pa +INSTALL
|
|
exists for the package,
|
|
it is then executed with the following arguments:
|
|
.Pp
|
|
.D1 Ar pkg-name Li PRE-INSTALL
|
|
.Pp
|
|
where
|
|
.Ar pkg-name
|
|
is the name of the package in question and
|
|
.Dq Li PRE-INSTALL
|
|
is a keyword denoting this as the preinstallation phase.
|
|
.Pp
|
|
.Sy Note :
|
|
The
|
|
.Dq Li PRE-INSTALL
|
|
keyword will not appear if separate scripts for pre-install and post-install
|
|
are given during package creation time (using the
|
|
.Fl i
|
|
and
|
|
.Fl I
|
|
flags to
|
|
.Xr pkg_create 1 ) .
|
|
.It
|
|
If
|
|
.Cm @option Cm extract-in-place
|
|
is not used, then the packing list (this is the
|
|
.Pa +CONTENTS
|
|
file) is now used as a guide for moving (or copying, as necessary) files from
|
|
the staging area into their final locations.
|
|
.It
|
|
If an mtree file
|
|
.Pa +MTREE_DIRS
|
|
exists for the package (see the
|
|
.Fl m
|
|
flag of
|
|
.Xr pkg_create 1 ) ,
|
|
then
|
|
.Xr mtree 8
|
|
is invoked as:
|
|
.Pp
|
|
.D1 Nm mtree Fl U f Pa +MTREE_DIRS Fl d e p Ar prefix
|
|
.Pp
|
|
where
|
|
.Ar prefix
|
|
is either the prefix specified with the
|
|
.Fl p
|
|
or
|
|
.Fl P
|
|
flag or,
|
|
if neither flag was specified, the name of the first directory named by a
|
|
.Ic @cwd
|
|
directive within this package.
|
|
.It
|
|
If a post-install script
|
|
.Pa +POST-INSTALL
|
|
exists for the package,
|
|
it is then executed with the following arguments:
|
|
.Pp
|
|
.D1 Ar pkg-name Li POST-INSTALL
|
|
.Pp
|
|
where
|
|
.Ar pkg-name
|
|
is the name of the package in question and
|
|
.Dq Li POST-INSTALL
|
|
is a keyword denoting this as the post-installation phase.
|
|
.Pp
|
|
.Sy Note :
|
|
The
|
|
.Dq Li POST-INSTALL
|
|
keyword will not appear if separate scripts for pre-install and post-install
|
|
are given during package creation time (using the
|
|
.Fl i
|
|
and
|
|
.Fl I
|
|
flags to
|
|
.Xr pkg_create 1 ) .
|
|
.Pp
|
|
Reasoning behind passing keywords such as
|
|
.Dq Li POST-INSTALL
|
|
and
|
|
.Dq Li PRE-INSTALL
|
|
is that this allows you to write a single
|
|
install
|
|
script that does both
|
|
.Dq before
|
|
and
|
|
.Dq after
|
|
actions.
|
|
But, separating the
|
|
functionality is more advantageous and easier from a maintenance viewpoint.
|
|
.It
|
|
After installation is complete, a copy of the
|
|
description
|
|
.Pq Pa +DESC ,
|
|
comment
|
|
.Pq Pa +COMMENT ,
|
|
pre-install script
|
|
.Pq Pa +INSTALL ,
|
|
post-install script
|
|
.Pq Pa +POST-INSTALL ,
|
|
deinstall script
|
|
.Pq Pa +DEINSTALL ,
|
|
post-deinstall script
|
|
.Pq Pa +POST-DEINSTALL ,
|
|
requirements script
|
|
.Pq Pa +REQUIRE ,
|
|
display
|
|
.Pq Pa +DISPLAY ,
|
|
mtree
|
|
.Pq Pa +MTREE_DIRS ,
|
|
and packing list
|
|
.Pq Pa +CONTENTS
|
|
files are copied into
|
|
.Pa /var/db/pkg/ Ns Aq Ar pkg-name
|
|
for subsequent possible use by
|
|
.Xr pkg_delete 1 .
|
|
Any package dependencies are recorded in the other packages'
|
|
.Pa /var/db/pkg/ Ns Ao Ar other-pkg Ac Ns Pa /+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
|
|
All the scripts are called with the environment variable
|
|
.Ev PKG_PREFIX
|
|
set to the installation prefix (see the
|
|
.Fl p
|
|
and
|
|
.Fl P
|
|
options above).
|
|
This allows a package author to write a script
|
|
that reliably performs some action on the directory where the package
|
|
is installed, even if the user might change it with the
|
|
.Fl p
|
|
or
|
|
.Fl P
|
|
flags to
|
|
.Nm .
|
|
.Sh ENVIRONMENT
|
|
The value of the
|
|
.Ev PKG_PATH
|
|
is used if a given package cannot be found.
|
|
The environment variable
|
|
should be 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.
|
|
.Pp
|
|
The environment variable
|
|
.Ev PKG_DBDIR
|
|
specifies an alternative location for the installed package database,
|
|
default location is
|
|
.Pa /var/db/pkg .
|
|
.Pp
|
|
The environment variables
|
|
.Ev PKG_TMPDIR
|
|
and
|
|
.Ev TMPDIR ,
|
|
in that order, are taken to name temporary directories where
|
|
.Nm
|
|
will attempt to create its staging area in.
|
|
If these variables are not present or if the directories named lack
|
|
sufficient space, then
|
|
.Nm
|
|
will use the first of
|
|
.Pa /var/tmp ,
|
|
.Pa /tmp
|
|
or
|
|
.Pa /usr/tmp
|
|
with sufficient space.
|
|
.Pp
|
|
The environment variable
|
|
.Ev PACKAGEROOT
|
|
specifies an alternate location for
|
|
.Nm
|
|
to fetch from.
|
|
The fetch URL is built using this environment variable and the automatic
|
|
directory logic that
|
|
.Nm
|
|
uses when the
|
|
.Fl r
|
|
option is invoked.
|
|
An example setting would be
|
|
.Qq Li ftp://ftp3.FreeBSD.org .
|
|
.Pp
|
|
The environment variable
|
|
.Ev PACKAGESITE
|
|
specifies an alternate location for
|
|
.Nm
|
|
to fetch from.
|
|
This variable subverts the automatic directory logic
|
|
that
|
|
.Nm
|
|
uses when the
|
|
.Fl r
|
|
option is invoked.
|
|
Thus it should be a complete URL to the remote package file(s).
|
|
.Pp
|
|
The environment variable
|
|
.Ev PKGDIR
|
|
specifies an alternative location to save downloaded packages to when
|
|
.Fl K
|
|
option is used.
|
|
.Sh FILES
|
|
.Bl -tag -width /var/db/pkg -compact
|
|
.It Pa /var/tmp
|
|
Temporary directory for creating the staging area, if environmental variables
|
|
.Ev PKG_TMPDIR
|
|
or
|
|
.Ev TMPDIR
|
|
do not point to a suitable directory.
|
|
.It Pa /tmp
|
|
Next choice if
|
|
.Pa /var/tmp
|
|
does not exist or has insufficient space.
|
|
.It Pa /usr/tmp
|
|
Last choice if
|
|
.Pa /var/tmp
|
|
and
|
|
.Pa /tmp
|
|
are not suitable for creating the staging area.
|
|
.It Pa /var/db/pkg
|
|
Default location of the installed package database.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr pkg_create 1 ,
|
|
.Xr pkg_delete 1 ,
|
|
.Xr pkg_info 1 ,
|
|
.Xr pkg_version 1 ,
|
|
.Xr mktemp 3 ,
|
|
.Xr sysconf 3 ,
|
|
.Xr mtree 8
|
|
.Sh AUTHORS
|
|
.An Jordan Hubbard
|
|
.Sh CONTRIBUTORS
|
|
.An John Kohl Aq jtk@rational.com
|
|
.Sh BUGS
|
|
Hard links between files in a distribution are only preserved if either
|
|
(1) the staging area is on the same file system as the target directory of
|
|
all the links to the file, or (2) all the links to the file are bracketed by
|
|
.Cm @cwd
|
|
directives in the contents file,
|
|
.Em and
|
|
the link names are extracted with a single
|
|
.Cm tar
|
|
command (not split between
|
|
invocations due to exec argument-space limitations--this depends on the
|
|
value returned by
|
|
.Fn sysconf _SC_ARG_MAX ) .
|
|
.Pp
|
|
Sure to be others.
|