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