diff options
Diffstat (limited to 'usr.sbin/pkg_add/pkg_add.1')
| -rw-r--r-- | usr.sbin/pkg_add/pkg_add.1 | 426 |
1 files changed, 426 insertions, 0 deletions
diff --git a/usr.sbin/pkg_add/pkg_add.1 b/usr.sbin/pkg_add/pkg_add.1 new file mode 100644 index 00000000000..711a969f055 --- /dev/null +++ b/usr.sbin/pkg_add/pkg_add.1 @@ -0,0 +1,426 @@ +.\" $OpenBSD: pkg_add.1,v 1.1 2003/10/19 18:38:06 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 vInfRMS +.Op Fl t Ar template +.Op Fl p Ar prefix +.Ar pkg-name Op Ar ... +.Sh DESCRIPTION +The +.Nm +command is used to extract packages that have been previously 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. +These packages are provided as a convenience for quickly installing software +that would otherwise need to be built manually. +.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 +Package names may be specified as filenames (which normally consist of the +package name itself plus the +.Dq .tgz , +.Dq .tar.gz , +or +.Dq .tar +suffix) or an FTP location in the form of an URL. +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 +Alternatively, it is possible to add packages interactively from within +the ftp client. +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 Ds +.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 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 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 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 +.Em 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 t Ar template +Use +.Ar template +as the input to +.Xr mkdtemp 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 (see CAVEATS). +Be sure to leave some number of +.Dq X +characters for +.Xr mkdtemp 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 the standard output 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 the standard input. +The complete packing list is also read from stdin, +and the contents then acted on as normal. +.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 list +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 +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. +.It +A staging area is created under +.Pa /var/tmp , +and the package is extracted into the staging area. +.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 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: +.Pp +.Bd -filled -offset indent -compact +.Cm mtree +.Fl u +.Fl f +.Ar mtreefile +.Fl d +.Fl e +.Fl p +.Pa prefix +.Ed +.Pp +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/<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 +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 . +.Sh ENVIRONMENT +.Bl -tag -width PKG_TMPDIR +.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_TMPDIR +Temporary area where packages 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 +.Bl -bullet -compact +.It +can hold executable scripts. +.El +.Pp +.Nm +looks through ${PKG_TMPDIR}, ${TMPDIR}, /var/tmp, /tmp, /usr/tmp +for such an area, in sequence. +.Pp +If ${TMPDIR} and /var/tmp are mounted noexec, you must set PKG_TMPDIR +to a suitable area, as +.Nm +has no way to check for noexec status except by failing to run installation +scripts. |