usr.sbin/pkg_install/add/pkg_add.1

   1 .\"
   2 .\" FreeBSD install - a package for the installation and maintainance
   3 .\" of non-core utilities.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" Jordan K. Hubbard
  15 .\"
  16 .\"
  17 .\"     @(#)pkg_add.1
  18 .\" $FreeBSD: src/usr.sbin/pkg_install/add/pkg_add.1,v 1.35.2.14 2002/12/29 16:35:43 schweikh Exp $
  19 .\" $DragonFly: src/usr.sbin/pkg_install/add/Attic/pkg_add.1,v 1.2 2003/06/17 04:29:59 dillon Exp $
  20 .\"
  21 .Dd November 25, 1994
  22 .Dt PKG_ADD 1
  23 .Os
  24 .Sh NAME
  25 .Nm pkg_add
  26 .Nd a utility for installing software package distributions
  27 .Sh SYNOPSIS
  28 .Nm
  29 .Op Fl vInfrRMS
  30 .Op Fl t Ar template
  31 .Op Fl p Ar prefix
  32 .Ar pkg-name Op Ar pkg-name ...
  33 .Sh DESCRIPTION
  34 The
  35 .Nm
  36 command is used to extract packages that have been previously created
  37 with the
  38 .Xr pkg_create 1
  39 command.
  40 .Sh WARNING
  41 .Bf -emphasis
  42 Since the
  43 .Nm
  44 command may execute scripts or programs contained within a package file,
  45 your system may be susceptible to
  46 .Dq Em trojan horses
  47 or other subtle
  48 attacks from miscreants who create dangerous package files.
  49 .Pp
  50 You are advised to verify the competence and identity of those who
  51 provide installable package files.  For extra protection, use the
  52 .Fl M
  53 flag to extract the package file, and inspect its contents and scripts to
  54 ensure it poses no danger to your system's integrity.  Pay particular
  55 attention to any +INSTALL, +POST-INSTALL, +DEINSTALL, +POST-DEINSTALL,
  56 +REQUIRE or +MTREE_DIRS files, and inspect the +CONTENTS file for
  57 .Cm @cwd ,
  58 .Cm @mode
  59 (check for setuid),
  60 .Cm @dirrm ,
  61 .Cm @exec ,
  62 and
  63 .Cm @unexec
  64 directives, and/or use the
  65 .Xr pkg_info 1
  66 command to examine the package file.
  67 .Ef
  68 .Sh OPTIONS
  69 The following command line arguments are supported:
  70 .Bl -tag -width indent
  71 .It Ar pkg-name Op Ar pkg-name ...
  72 The named packages are installed.  A package name of - will cause
  73 .Nm
  74 to read from stdin.
  75 If the packages are not found in the current
  76 working directory,
  77 .Nm
  78 will search them in each directory named by
  79 .Ev PKG_PATH .
  80 .It Fl v
  81 Turn on verbose output.
  82 .It Fl I
  83 If a installation scripts (pre-install or post-install) exist for a given
  84 package, do not execute them.
  85 .It Fl n
  86 Don't actually install a package, just report the steps that
  87 would be taken if it was.
  88 .It Fl R
  89 Do not record the installation of a package.  This means
  90 that you cannot deinstall it later, so only use this option if
  91 you know what you are doing!
  92 .It Fl r
  93 Use the remote fetching feature.
  94 This will determine the appropriate
  95 objformat and release and then fetch and install the package.
  96 .It Fl f
  97 Force installation to proceed even if prerequisite packages are not
  98 installed or the requirements script fails.  Although
  99 .Nm
 100 will still try to find and auto-install missing prerequisite packages,
 101 a failure to find one will not be fatal.
 102 .It Fl p Ar prefix
 103 Set
 104 .Ar prefix
 105 as the directory in which to extract files from a package.
 106 If a package has set its default directory, it will be overridden
 107 by this flag.  Note that only the first
 108 .Cm @cwd
 109 directive will be replaced, since
 110 .Nm
 111 has no way of knowing which directory settings are relative and
 112 which are absolute.  It is rare in any case to see more than one
 113 directory transition made, but when such does happen and you wish
 114 to have control over *all* directory transitions, then you
 115 may then wish to look into the use of
 116 .Cm MASTER
 117 and
 118 .Cm SLAVE
 119 modes (see the
 120 .Fl M
 121 and
 122 .Fl S
 123 options).
 124 .It Fl t Ar template
 125 Use
 126 .Ar template
 127 as the input to
 128 .Xr mktemp 3
 129 when creating a
 130 .Dq staging area .
 131 By default, this is the string
 132 .Pa /var/tmp/instmp.XXXXXX ,
 133 but it may be necessary to override it in the situation where
 134 space in your
 135 .Pa /var/tmp
 136 directory is limited.  Be sure to leave some number of `X' characters
 137 for
 138 .Xr mktemp 3
 139 to fill in with a unique ID.
 140 .Pp
 141 You can get a performance boost by setting the staging area
 142 .Ar template
 143 to reside on the same disk partition as target directories for package
 144 file installation; often this is
 145 .Pa /usr .
 146 .It Fl M
 147 Run in
 148 .Cm MASTER
 149 mode.  This is a very specialized mode for running
 150 .Nm
 151 and is meant to be run in conjunction with
 152 .Cm SLAVE
 153 mode.  When run in this mode,
 154 .Nm
 155 does no work beyond extracting the package into a temporary staging
 156 area (see the
 157 .Fl t
 158 option), reading in the packing list, and then dumping it (prefaced by
 159 the current staging area) to stdout where it may be filtered by a
 160 program such as
 161 .Xr sed 1 .
 162 When used in conjunction with
 163 .Cm SLAVE
 164 mode, it allows you to make radical changes to the package structure
 165 before acting on its contents.
 166 .It Fl S
 167 Run in
 168 .Cm SLAVE
 169 mode.  This is a very specialized mode for running
 170 .Nm
 171 and is meant to be run in conjunction with
 172 .Cm MASTER
 173 mode.  When run in this mode,
 174 .Nm
 175 expects the release contents to be already extracted and waiting
 176 in the staging area, the location of which is read as a string
 177 from stdin.  The complete packing list is also read from stdin,
 178 and the contents then acted on as normal.
 179 .El
 180 .Pp
 181 One or more
 182 .Ar pkg-name
 183 arguments may be specified, each being either a file containing the
 184 package (these usually end with a
 185 .Dq .tgz
 186 suffix) or a
 187 URL pointing at a file available on an ftp site.  Thus you may
 188 extract files directly from their anonymous ftp locations (e.g.\&
 189 .Nm
 190 .Li ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/shells/bash-1.14.7.tgz ) .
 191 Note:  If you wish to use
 192 .Bf -emphasis
 193 passive mode
 194 .Ef
 195 ftp in such transfers, set
 196 the variable
 197 .Bf -emphasis
 198 FTP_PASSIVE_MODE
 199 .Ef
 200 to some value in your environment.  Otherwise, the more standard
 201 ACTIVE mode may be used.  If
 202 .Nm
 203 consistently fails to fetch a package from a site known to work,
 204 it may be because you have a firewall that demands the usage of
 205 .Bf -emphasis
 206 passive mode
 207 .Ef
 208 ftp.
 209 .Sh TECHNICAL DETAILS
 210 The
 211 .Nm
 212 utility is fairly simple.  It extracts each package's "packing list"
 213 into a special staging directory, parses it,
 214 and then runs through the following sequence to fully extract the contents:
 215 .Bl -enum
 216 .It
 217 Check if the package is already recorded as installed.  If so,
 218 terminate installation.
 219 .It
 220 Scan all the package dependencies (from
 221 .Cm @pkgdep
 222 directives, see
 223 .Xr pkg_create 1 )
 224 and make sure each one is met.  If not, try and find the missing
 225 dependencies' packages and auto-install them; if they can't be found
 226 the installation is terminated.
 227 .It
 228 Search for any
 229 .Cm @option
 230 directives which control how the package is added to the system.
 231 At the time of this writing, the only currently implemented option is
 232 .Cm @option extract-in-place
 233 which will cause the package to be extracted directly into its
 234 prefix directory without moving through a staging area in
 235 .Pa /tmp .
 236 .It
 237 If
 238 .Cm @option extract-in-place
 239 is enabled, the package is now extracted directly into its
 240 final location, otherwise it is extracted into the staging area.
 241 .It
 242 If the package contains a
 243 .Ar require
 244 file (see
 245 .Xr pkg_create 1 ) ,
 246 then execute it with the following arguments:
 247 .Bd -ragged -offset indent -compact
 248 .Ar pkg-name
 249 .Ar INSTALL
 250 .Ed
 251 where
 252 .Ar pkg-name
 253 is the name of the package in question and the
 254 .Ar INSTALL
 255 keyword denotes this as an installation requirements check (useful if
 256 you want to have one script serving multiple functions).
 257 .It
 258 If a
 259 .Ar pre-install
 260 script exists for the package, it is then executed with the following
 261 arguments:
 262 .Bd -ragged -offset indent -compact
 263 .Cm script
 264 .Ar pkg-name
 265 .Ar PRE-INSTALL
 266 .Ed
 267 .Pp
 268 where
 269 .Ar pkg-name
 270 is the name of the package in question and
 271 .Ar PRE-INSTALL
 272 is a keyword denoting this as the preinstallation phase.
 273 .Pp
 274 .Sy Note :
 275 The
 276 .Ar PRE-INSTALL
 277 keyword will not appear if separate scripts for pre-install and post-install
 278 are given during package creation time (using the
 279 .Fl i
 280 and
 281 .Fl I
 282 flags to
 283 .Xr pkg_create 1 ) .
 284 .It
 285 If
 286 .Cm @option extract-in-place
 287 is not used, then the packing list (this is the
 288 .Pa +CONTENTS
 289 file) is now used as a guide for moving (or copying, as necessary) files from
 290 the staging area into their final locations.
 291 .It
 292 If the package contains an
 293 .Ar mtreefile
 294 file (see
 295 .Xr pkg_create 1 ) ,
 296 then mtree is invoked as:
 297 .Bd -ragged -offset indent -compact
 298 .Cm mtree
 299 .Fl u
 300 .Fl f
 301 .Ar mtreefile
 302 .Fl d
 303 .Fl e
 304 .Fl p
 305 .Pa prefix
 306 .Ed
 307 where
 308 .Pa prefix
 309 is either the prefix specified with the
 310 .Fl p
 311 flag or, if no
 312 .Fl p
 313 flag was specified, the name of the first directory named by a
 314 .Cm @cwd
 315 directive within this package.
 316 .It
 317 If a
 318 .Ar post-install
 319 script exists for the package, it is then executed as
 320 .Bd -ragged -offset indent -compact
 321 .Cm script
 322 .Ar pkg-name
 323 .Ar POST-INSTALL
 324 .Ed
 325 where
 326 .Ar pkg-name
 327 is the name of the package in question and
 328 .Ar POST-INSTALL
 329 is a keyword denoting this as the post-installation phase.
 330 .Pp
 331 .Sy Note :
 332 The
 333 .Ar POST-INSTALL
 334 keyword will not appear if separate scripts for pre-install and post-install
 335 are given during package creation time (using the
 336 .Fl i
 337 and
 338 .Fl I
 339 flags to
 340 .Xr pkg_create 1 ) .
 341 .Pp
 342 Reasoning behind passing keywords such as
 343 .Ar POST-INSTALL
 344 and
 345 .Ar PRE-INSTALL
 346 is that this allows you to write a single
 347 .Ar install
 348 script that does both
 349 .Dq before and after
 350 actions.
 351 But, separating the
 352 functionality is more advantageous and easier from a maintenance viewpoint.
 353 .It
 354 After installation is complete, a copy of the packing list,
 355 .Ar deinstall
 356 script, description, and display files are copied into
 357 .Pa /var/db/pkg/<pkg-name>
 358 for subsequent possible use by
 359 .Xr pkg_delete 1 .
 360 Any package dependencies are recorded in the other packages'
 361 .Pa /var/db/pkg/<other-pkg>/+REQUIRED_BY
 362 file
 363 (if the environment variable PKG_DBDIR is set, this overrides the
 364 .Pa /var/db/pkg/
 365 path shown above).
 366 .It
 367 Finally, the staging area is deleted and the program terminates.
 368 .El
 369 .Pp
 370 All the scripts are called with the environment variable
 371 .Ev PKG_PREFIX
 372 set to the installation prefix (see the
 373 .Fl p
 374 option above).  This allows a package author to write a script
 375 that reliably performs some action on the directory where the package
 376 is installed, even if the user might change it with the
 377 .Fl p
 378 flag to
 379 .Cm pkg_add .
 380 .Sh ENVIRONMENT
 381 The value of the
 382 .Ev PKG_PATH
 383 is used if a given package can't be found.  The environment variable
 384 should be a series of entries separated by colons.  Each entry
 385 consists of a directory name.
 386 The current directory may be indicated
 387 implicitly by an empty directory name, or explicitly by a single
 388 period.
 389 .Pp
 390 The environment variable
 391 .Ev PKG_DBDIR
 392 specifies an alternative location for the installed package database.
 393 .Pp
 394 The environment variables
 395 .Ev PKG_TMPDIR
 396 and
 397 .Ev TMPDIR ,
 398 in that order, are taken to name temporary directories where
 399 .Nm
 400 will attempt to create its staging area in.
 401 If these variables are not present or if the directories named lack
 402 sufficient space, then
 403 .Nm
 404 will use the first of
 405 .Pa /var/tmp ,
 406 .Pa /tmp
 407 or
 408 .Pa /usr/tmp
 409 with sufficient space.
 410 .Pp
 411 The environment variable
 412 .Ev PACKAGEROOT
 413 specifies an alternate location for
 414 .Nm
 415 to fetch from.
 416 The fetch URL is built using this environment variable and the automatic
 417 directory logic that
 418 .Nm
 419 uses when the
 420 .Fl r
 421 option is invoked.
 422 An example setting would be
 423 .Qq Li ftp://ftp3.FreeBSD.org .
 424 .Pp
 425 The environment variable
 426 .Ev PACKAGESITE
 427 specifies an alternate location for
 428 .Nm
 429 to fetch from.
 430 This variable subverts the automatic directory logic
 431 that
 432 .Nm
 433 uses when the
 434 .Fl r
 435 option is invoked.
 436 Thus it should be a complete URL to the remote package file(s).
 437 .Sh FILES
 438 .Bl -tag -width /var/db/pkg -compact
 439 .It Pa /var/tmp
 440 Temporary directory for creating the staging area, if environmental variables
 441 .Ev PKG_TMPDIR
 442 or
 443 .Ev TMPDIR
 444 do not point to a suitable directory.
 445 .It Pa /tmp
 446 Next choice if
 447 .Pa /var/tmp
 448 does not exist or has insufficient space.
 449 .It Pa /usr/tmp
 450 Last choice if
 451 .Pa /var/tmp
 452 and
 453 .Pa /tmp
 454 are not suitable for creating the staging area.
 455 .It Pa /var/db/pkg
 456 Default location of the installed package database.
 457 .El
 458 .Sh SEE ALSO
 459 .Xr pkg_create 1 ,
 460 .Xr pkg_delete 1 ,
 461 .Xr pkg_info 1 ,
 462 .Xr pkg_update 1 ,
 463 .Xr pkg_version 1 ,
 464 .Xr mktemp 3 ,
 465 .Xr sysconf 3 ,
 466 .Xr mtree 8
 467 .Sh AUTHORS
 468 .An Jordan Hubbard
 469 .Sh CONTRIBUTORS
 470 .An John Kohl Aq jtk@rational.com
 471 .Sh BUGS
 472 Hard links between files in a distribution are only preserved if either
 473 (1) the staging area is on the same file system as the target directory of
 474 all the links to the file, or (2) all the links to the file are bracketed by
 475 .Cm @cwd
 476 directives in the contents file,
 477 .Em and
 478 the link names are extracted with a single
 479 .Cm tar
 480 command (not split between
 481 invocations due to exec argument-space limitations--this depends on the
 482 value returned by
 483 .Fn sysconf _SC_ARG_MAX ) .
 484 .Pp
 485 Sure to be others.