671 lines
18 KiB
Groff
671 lines
18 KiB
Groff
.\" $NetBSD: pkg_add.1,v 1.63 2006/04/08 23:05:38 wiz 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 April 3, 2006
|
|
.Dt PKG_ADD 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm pkg_add
|
|
.Nd a utility for installing and upgrading software package distributions
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl AfILMnRSuVv
|
|
.Op Fl K Ar pkg_dbdir
|
|
.Op Fl p Ar prefix
|
|
.Op Fl s Ar verification-type
|
|
.Op Fl t Ar template
|
|
.Op Fl W Ar viewbase
|
|
.Op Fl w Ar view
|
|
.Ar \fR[[ftp|http]://[\fIuser\fR[:\fIpassword]\fR@]\fIhost\fR[:\fIport\fR]][/\fIpath/\fR]pkg-name ...
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
command is used to extract and upgrade packages that have been
|
|
previously created with the
|
|
.Xr pkg_create 1
|
|
command.
|
|
Packages are prepared collections of pre-built binaries, documentation,
|
|
configurations, installation instructions and/or other files.
|
|
.Nm
|
|
can recursively install other packages that the current package
|
|
depends on or requires from both local disk and via FTP or HTTP.
|
|
.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 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 digital signatures provided where possible
|
|
(see the
|
|
.Fl s
|
|
option), or, failing that, 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
|
|
.Pa +INSTALL ,
|
|
.Pa +DEINSTALL ,
|
|
.Pa +REQUIRE ,
|
|
or
|
|
.Pa +MTREE_DIRS
|
|
files, and inspect the
|
|
.Pa +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 [ ... ]
|
|
The named packages are installed.
|
|
.Ar pkg-name
|
|
may be either a URL or a local pathname,
|
|
a package name of "-" 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 the
|
|
.Ev PKG_PATH
|
|
environment variable.
|
|
Any dependencies required by the installed package will be searched
|
|
in the same location that the original package was installed from.
|
|
.It Fl A
|
|
Mark package as installed automatically, as dependency of another
|
|
package.
|
|
You can use
|
|
.Dl Ic pkg_admin set automatic=YES
|
|
to mark packages this way after installation, and
|
|
.Dl Ic pkg_admin unset automatic
|
|
to remove the mark.
|
|
If you
|
|
.Nm
|
|
a package without specifying
|
|
.Fl A
|
|
after it had already been automatically installed, the mark is
|
|
removed.
|
|
.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.
|
|
This flag also overrides the fatal error when the operating system or
|
|
architecture the package was built on differ from that of the host.
|
|
.It Fl I
|
|
If an installation script exists for a given package, do not execute it.
|
|
.It Fl K Ar pkg_dbdir
|
|
Set
|
|
.Ar pkg_dbdir
|
|
as the package database directory.
|
|
If this option isn't specified, then the package database directory is
|
|
taken from the value of the environment variable
|
|
.Ev PKG_DBDIR
|
|
if it's set, otherwise it defaults to
|
|
.Pa /var/db/pkg .
|
|
.It Fl L
|
|
Don't add the package to any views after installation.
|
|
.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 n
|
|
Don't actually install a package, just report the steps that
|
|
would be taken if it was.
|
|
.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).
|
|
.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 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 s Ar verification-type
|
|
Use a callout to an external program to verify the binary package
|
|
being installed against an existing detached signature file.
|
|
The signature file must reside in the same directory
|
|
as the binary package.
|
|
At the present time, the following verification types
|
|
are defined: none, gpg and pgp5.
|
|
The signature will be verified at install time, and the results
|
|
will be displayed.
|
|
If the signature type is anything other than none, the user will be asked if
|
|
.Nm
|
|
should proceed to install the binary package.
|
|
The user must then take the decision whether to proceed or not, depending
|
|
upon the amount of trust that is placed in the signatory of the binary
|
|
package.
|
|
Please note that, at the current time, it is not possible to use
|
|
the verification feature when using
|
|
.Nm
|
|
to add a binary package via a URL - the package, and the related
|
|
detached signature file, must be local
|
|
for the verification to work.
|
|
.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
|
|
.Sq 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 u
|
|
If the package that's being installed is already installed, either
|
|
in the same or a different version, an update is performed.
|
|
If this is specified twice, then any dependant packages that are
|
|
too old will also be updated to fulfill the dependency.
|
|
See below for a more detailed description of the process.
|
|
.It Fl V
|
|
Print version number and exit.
|
|
.It Fl v
|
|
Turn on verbose output.
|
|
.It Fl W Ar viewbase
|
|
Set
|
|
.Ar viewbase
|
|
as the base directory for the managed views.
|
|
The default
|
|
.Ar viewbase
|
|
directory is set by
|
|
.Xr pkg_view 1 .
|
|
This value also may be set from the
|
|
.Ev LOCALBASE
|
|
environment variable.
|
|
.It Fl w Ar view
|
|
Set the
|
|
.Ar view
|
|
to which packages should be added after installation.
|
|
The default
|
|
.Ar view
|
|
is set by
|
|
.Xr pkg_view 1 .
|
|
This value also may be set from the
|
|
.Ev PKG_VIEW
|
|
environment variable.
|
|
.El
|
|
.Pp
|
|
One or more
|
|
.Ar pkg-name
|
|
arguments may be specified, each being either a file containing the
|
|
package (these usually ending with the
|
|
.Dq .tgz
|
|
suffix) or a
|
|
URL pointing at a file available on an ftp or web site.
|
|
Thus you may extract files directly from their anonymous ftp or WWW
|
|
locations (e.g.,
|
|
.Nm
|
|
ftp://ftp.NetBSD.org/pub/NetBSD/packages/2.0/i386/shells/bash-3.0nb1.tgz
|
|
or
|
|
.Nm
|
|
http://www.example.org/packages/screen-4.0.tbz).
|
|
Note: For ftp transfers, 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
|
|
.Nm
|
|
extracts each package's
|
|
.Dq packing list
|
|
into a special staging directory in /var/tmp (or $PKG_TMPDIR if set)
|
|
and then runs through the following sequence to fully extract the contents
|
|
of the package:
|
|
.Bl -enum -offset indent
|
|
.It
|
|
A check is made to determine if the package or another version of it
|
|
is already recorded as installed.
|
|
If it is,
|
|
installation is terminated if the
|
|
.Fl u
|
|
option is not given.
|
|
.Pp
|
|
If the
|
|
.Fl u
|
|
option is given, it's assumed the package should be replaced by the
|
|
new version instead.
|
|
Before doing so, all packages that depend on the
|
|
pkg being upgraded are checked if they also work with the new version.
|
|
If that test is successful, replacing is prepared by moving an existing
|
|
.Pa +REQUIRED_BY
|
|
file aside (if it exists), and running
|
|
.Xr pkg_delete 1
|
|
on the installed package.
|
|
Installation then proceeds as if the package
|
|
was not installed, and restores the
|
|
.Pa +REQUIRED_BY
|
|
file afterwards.
|
|
.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
|
|
All package dependencies (from
|
|
.Cm @pkgdep
|
|
directives, see
|
|
.Xr pkg_create 1 )
|
|
are read from the packing list.
|
|
If any of these required packages are 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.
|
|
If the
|
|
.Fl u
|
|
option was specified twice, any required packages that are installed,
|
|
but which have a version number that is considered to be too old,
|
|
are also updated.
|
|
The dependant packages are found according to the normal
|
|
.Ev PKG_PATH
|
|
rules.
|
|
.It
|
|
A search is made for any
|
|
.Cm @option
|
|
directives which control how the package is added to the system.
|
|
The only currently implemented option is
|
|
.Cm @option extract-in-place ,
|
|
which causes the package to be extracted directly into its
|
|
prefix directory rather than moving it through a staging area in
|
|
.Pa /var/tmp .
|
|
.It
|
|
If
|
|
.Cm @option extract-in-place
|
|
is enabled, the package is now extracted directly into its
|
|
final location, otherwise it is extracted into the staging area.
|
|
.It
|
|
The package build information is extracted from the
|
|
.Pa +BUILD_INFO
|
|
file and compared against the result of
|
|
.Xr uname 3 .
|
|
If the operating system or architecture of the package differ from
|
|
that of the host, installation is aborted.
|
|
This behavior is overridable with the
|
|
.Fl f
|
|
flag.
|
|
.It
|
|
The package build information from
|
|
.Pa +BUILD_INFO
|
|
is then checked for
|
|
.Ev USE_ABI_DEPENDS=NO
|
|
(or
|
|
.Ev IGNORE_RECOMMENDED ) .
|
|
If the package was built with ABI dependency recommendations ignored,
|
|
a warning will be issued.
|
|
.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
|
|
If
|
|
.Cm @option extract-in-place
|
|
is not present in the packing list,
|
|
then it is used as a guide for moving (or copying, as necessary) files from
|
|
the staging area into their final locations.
|
|
.It
|
|
If the package contains an
|
|
.Ar mtreefile
|
|
file (see
|
|
.Xr pkg_create 1 ) ,
|
|
then mtree is invoked as:
|
|
.Bd -filled -offset indent -compact
|
|
.Cm mtree
|
|
.Fl u
|
|
.Fl f
|
|
.Ar mtreefile
|
|
.Fl d
|
|
.Fl e
|
|
.Fl p
|
|
.Pa prefix
|
|
.Ed
|
|
where
|
|
.Pa prefix
|
|
is either the prefix specified with the
|
|
.Fl p
|
|
flag or, if no
|
|
.Fl p
|
|
flag was specified, the name of the first directory named by a
|
|
.Cm @cwd
|
|
directive within this package.
|
|
.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/\*[Lt]pkg-name\*[Gt]
|
|
for subsequent possible use by
|
|
.Xr pkg_delete 1 .
|
|
Any package dependencies are recorded in the other packages'
|
|
.Pa /var/db/pkg/\*[Lt]other-pkg\*[Gt]/+REQUIRED_BY
|
|
file
|
|
(if an alternate package database directory is specified, then it
|
|
overrides the
|
|
.Pa /var/db/pkg
|
|
path shown above).
|
|
.It
|
|
If the package is a depoted package, then add it to the default view.
|
|
.It
|
|
The staging area is deleted and the program terminates.
|
|
.It
|
|
Finally, if we were upgrading a package, any
|
|
.Pa +REQUIRED_BY
|
|
file that was moved aside before upgrading was started is now moved
|
|
back into place.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Ar install
|
|
and
|
|
.Ar require
|
|
scripts are called with the environment variable
|
|
.Ev PKG_PREFIX
|
|
set to the installation prefix (see the
|
|
.Fl p
|
|
option 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
|
|
flag to
|
|
.Cm pkg_add .
|
|
The scripts are also called with the
|
|
.Ev PKG_METADATA_DIR
|
|
environment variable set to the location of the
|
|
.Pa +*
|
|
meta-data files, and with the
|
|
.Ev PKG_REFCOUNT_DBDIR
|
|
environment variable set to the location of the package reference counts
|
|
database directory.
|
|
.Sh ENVIRONMENT
|
|
.Bl -tag -width PKG_TMPDIR
|
|
.It Ev LOCALBASE
|
|
This is the location of the
|
|
.Ar viewbase
|
|
directory in which all the views are managed.
|
|
The default
|
|
.Ar viewbase
|
|
directory is
|
|
.Pa /usr/pkg .
|
|
.It Ev PKG_DBDIR
|
|
If the
|
|
.Fl K
|
|
flag isn't given, then
|
|
.Ev PKG_DBDIR
|
|
is the location of the package database directory.
|
|
The default package database directory is
|
|
.Pa /var/db/pkg .
|
|
.It Ev PKG_PATH
|
|
The value of the
|
|
.Ev PKG_PATH
|
|
is used if a given package can't be found, it's usually set to
|
|
.Pa /usr/pkgsrc/packages/All .
|
|
The environment variable
|
|
should be a series of entries separated by semicolons.
|
|
Each entry consists of a directory name or URL.
|
|
The current directory may be indicated implicitly by an empty directory
|
|
name, or explicitly by a single period.
|
|
FTP URLs may not end with a slash.
|
|
.It Ev PKG_REFCOUNT_DBDIR
|
|
Location of the package reference counts database directory.
|
|
The default location is the path to the package database directory with
|
|
.Dq .refcount
|
|
appended to the path, e.g.
|
|
.Pa /var/db/pkg.refcount .
|
|
.It Ev PKG_TMPDIR
|
|
Staging directory for installing packages, defaults to /var/tmp.
|
|
Set to directory with lots of free disk if you run out of
|
|
space when installing a binary package.
|
|
.It Ev PKG_VIEW
|
|
The default view can be specified in the
|
|
.Ev PKG_VIEW
|
|
environment variable.
|
|
.El
|
|
.Sh EXAMPLES
|
|
In all cases,
|
|
.Nm
|
|
will try to install binary packages listed in dependencies list.
|
|
.Pp
|
|
You can specify a compiled binary package explicitly on the command line.
|
|
.Bd -literal
|
|
# pkg_add /usr/pkgsrc/packages/All/tcsh-6.14.00.tgz
|
|
.Ed
|
|
.Pp
|
|
If you omit the version number,
|
|
.Nm
|
|
will install the latest version available.
|
|
With
|
|
.Fl v ,
|
|
.Nm
|
|
emits more messages to terminal.
|
|
.Bd -literal
|
|
# pkg_add -v /usr/pkgsrc/packages/All/unzip
|
|
.Ed
|
|
.Pp
|
|
You can grab a compiled binary package from remote location by specifying
|
|
a URL.
|
|
The URL can be put into an environment variable,
|
|
.Ev PKG_PATH .
|
|
.Bd -literal
|
|
# pkg_add -v ftp://ftp.NetBSD.org/pub/NetBSD/packages/2.0/i386/All/firefox-1.0.3.tgz
|
|
|
|
# export PKG_PATH=ftp://ftp.NetBSD.org/pub/NetBSD/packages/2.0/i386/All
|
|
# pkg_add -v firefox
|
|
.Ed
|
|
.Pp
|
|
Over time, as problems are found in packages, they will be moved
|
|
from the
|
|
.Pa All
|
|
subdirectory into the
|
|
.Pa vulnerable
|
|
subdirectory.
|
|
If you want to accept vulnerable packages by default
|
|
(and know what you are doing),
|
|
you can add the
|
|
.Pa vulnerable
|
|
directory to your
|
|
.Ev PKG_PATH
|
|
like this:
|
|
.Bd -literal
|
|
# export PKG_PATH="ftp://ftp.NetBSD.org/pub/NetBSD/packages/2.0/i386/All;ftp://ftp.NetBSD.org/pub/NetBSD/packages/2.0/i386/vulnerable"
|
|
.Ed
|
|
.Pp
|
|
(The quotes are needed because semicolon
|
|
.Pq Sq \&;
|
|
is a shell meta-character.)
|
|
If you do this, consider installing and using the
|
|
.Pa security/audit-packages
|
|
package and running it after every
|
|
.Nm .
|
|
.Sh SEE ALSO
|
|
.Xr pkg_admin 1 ,
|
|
.Xr pkg_create 1 ,
|
|
.Xr pkg_delete 1 ,
|
|
.Xr pkg_info 1 ,
|
|
.Xr mktemp 3 ,
|
|
.Xr sysconf 3 ,
|
|
.Xr packages 7 ,
|
|
.Xr mtree 8
|
|
.Sh AUTHORS
|
|
.Bl -tag -width indent -compact
|
|
.It "Jordan Hubbard"
|
|
Initial work and ongoing development.
|
|
.It "John Kohl"
|
|
.Nx
|
|
refinements.
|
|
.It "Hubert Feyrer"
|
|
.Nx
|
|
wildcard dependency processing, pkgdb, upgrading, etc.
|
|
.It Thomas Klausner
|
|
HTTP support.
|
|
.El
|
|
.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
|
|
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
|
|
Package upgrading needs a lot more work to be really universal.
|
|
.Pp
|
|
Sure to be others.
|