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 .\" $FreeBSD$
  17 .\"
  18 .Dd January 4, 2009
  19 .Dt PKG_ADD 1
  20 .Os
  21 .Sh NAME
  22 .Nm pkg_add
  23 .Nd a utility for installing software package distributions
  24 .Sh SYNOPSIS
  25 .Nm
  26 .Op Fl viInfFrRMSK
  27 .Op Fl t Ar template
  28 .Op Fl p Ar prefix
  29 .Op Fl P Ar prefix
  30 .Op Fl C Ar chrootdir
  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.
  51 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.
  55 Pay particular
  56 attention to any +INSTALL, +POST-INSTALL, +DEINSTALL, +POST-DEINSTALL,
  57 +REQUIRE or +MTREE_DIRS files, and inspect the +CONTENTS file for
  58 .Cm @cwd ,
  59 .Cm @mode
  60 (check for setuid),
  61 .Cm @dirrm ,
  62 .Cm @exec ,
  63 and
  64 .Cm @unexec
  65 directives, and/or use the
  66 .Xr pkg_info 1
  67 command to examine the package file.
  68 .Ef
  69 .Sh OPTIONS
  70 The following command line arguments are supported:
  71 .Bl -tag -width indent
  72 .It Ar pkg-name Op Ar pkg-name ...
  73 The named packages are installed.
  74 A package name of
  75 .Fl
  76 will cause
  77 .Nm
  78 to read from stdin.
  79 If the packages are not found in the current
  80 working directory,
  81 .Nm
  82 will search them in each directory named by
  83 .Ev PKG_PATH .
  84 .It Fl v , -verbose
  85 Turn on verbose output.
  86 .It Fl K , -keep
  87 Keep any downloaded package in
  88 .Ev PKGDIR
  89 if it is defined or in current directory by default.
  90 .It Fl i , -no-deps
  91 Install the package without fetching and installing
  92 dependencies.
  93 .It Fl I , -no-script
  94 If any installation scripts (pre-install or post-install) exist for a given
  95 package, do not execute them.
  96 .It Fl n , -dry-run
  97 Do not actually install a package, just report the steps that
  98 would be taken if it was.
  99 .It Fl R , -no-record
 100 Do not record the installation of a package.
 101 This means
 102 that you cannot deinstall it later, so only use this option if
 103 you know what you are doing!
 104 .It Fl r , -remote
 105 Use the remote fetching feature.
 106 This will determine the appropriate
 107 objformat and release and then fetch and install the package.
 108 .It Fl f , -force
 109 Force installation to proceed even if prerequisite packages are not
 110 installed or the requirements script fails.
 111 Although
 112 .Nm
 113 will still try to find and auto-install missing prerequisite packages,
 114 a failure to find one will not be fatal.
 115 .It Fl F
 116 Already installed packages are not an error.
 117 .It Fl p , -prefix Ar prefix
 118 Set
 119 .Ar prefix
 120 as the directory in which to extract files from a package.
 121 If a package has set its default directory, it will be overridden
 122 by this flag.
 123 Note that only the first
 124 .Cm @cwd
 125 directive will be replaced, since
 126 .Nm
 127 has no way of knowing which directory settings are relative and
 128 which are absolute.
 129 It is rare in any case to see more than one
 130 directory transition made, but when such does happen and you wish
 131 to have control over *all* directory transitions, then you
 132 may then wish to look into the use of
 133 .Cm MASTER
 134 and
 135 .Cm SLAVE
 136 modes (see the
 137 .Fl M
 138 and
 139 .Fl S
 140 options).
 141 If the
 142 .Fl p
 143 flag appears after any
 144 .Fl P
 145 flag on the command line, it overrides its effect, causing
 146 .Nm
 147 not to use the given
 148 .Ar prefix
 149 recursively.
 150 .It Fl P Ar prefix
 151 Does the same as the
 152 .Fl p
 153 option, except that the given
 154 .Ar prefix
 155 is also used recursively for the dependency packages, if any.
 156 If the
 157 .Fl P
 158 flag appears after any
 159 .Fl p
 160 flag on the command line, it overrides its effect, causing
 161 .Nm
 162 to use the given
 163 .Ar prefix
 164 recursively.
 165 .It Fl t , -template Ar template
 166 Use
 167 .Ar template
 168 as the input to
 169 .Xr mktemp 3
 170 when creating a
 171 .Dq staging area .
 172 By default, this is the string
 173 .Pa /var/tmp/instmp.XXXXXX ,
 174 but it may be necessary to override it in the situation where
 175 space in your
 176 .Pa /var/tmp
 177 directory is limited.
 178 Be sure to leave some number of `X' characters
 179 for
 180 .Xr mktemp 3
 181 to fill in with a unique ID.
 182 .Pp
 183 You can get a performance boost by setting the staging area
 184 .Ar template
 185 to reside on the same disk partition as target directories for package
 186 file installation; often this is
 187 .Pa /usr .
 188 .It Fl M , -master
 189 Run in
 190 .Cm MASTER
 191 mode.
 192 This is a very specialized mode for running
 193 .Nm
 194 and is meant to be run in conjunction with
 195 .Cm SLAVE
 196 mode.
 197 When run in this mode,
 198 .Nm
 199 does no work beyond extracting the package into a temporary staging
 200 area (see the
 201 .Fl t
 202 option), reading in the packing list, and then dumping it (prefaced by
 203 the current staging area) to stdout where it may be filtered by a
 204 program such as
 205 .Xr sed 1 .
 206 When used in conjunction with
 207 .Cm SLAVE
 208 mode, it allows you to make radical changes to the package structure
 209 before acting on its contents.
 210 .It Fl S , -slave
 211 Run in
 212 .Cm SLAVE
 213 mode.
 214 This is a very specialized mode for running
 215 .Nm
 216 and is meant to be run in conjunction with
 217 .Cm MASTER
 218 mode.
 219 When run in this mode,
 220 .Nm
 221 expects the release contents to be already extracted and waiting
 222 in the staging area, the location of which is read as a string
 223 from stdin.
 224 The complete packing list is also read from stdin,
 225 and the contents then acted on as normal.
 226 .It Fl C , -chroot Ar chrootdir
 227 Before doing any operations,
 228 .Xr chroot 2
 229 to the
 230 .Ar chrootdir
 231 directory so that all package files, and the package database, are
 232 installed to
 233 .Ar chrootdir .
 234 Note that
 235 .Ar chrootdir
 236 needs to be a fairly complete file system, including everything normally
 237 needed by
 238 .Nm
 239 to run.
 240 This flag was added to help support operations done by
 241 .Xr sysinstall 8
 242 and is not expected to be useful for much else.
 243 Be careful that
 244 .Ar chrootdir
 245 is properly configured and cannot be modified by normal users,
 246 versions of commands like
 247 .Xr fetch 1
 248 may be run inside
 249 .Ar chrootdir
 250 as a side effect.
 251 .El
 252 .Pp
 253 One or more
 254 .Ar pkg-name
 255 arguments may be specified, each being either a file containing the
 256 package (these usually end with a
 257 .Dq .tbz
 258 suffix) or a
 259 URL pointing at a file available on an ftp site.
 260 Thus you may
 261 extract files directly from their anonymous ftp locations (e.g.\&
 262 .Nm
 263 .Li ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/shells/bash-1.14.7.tbz ) .
 264 Note: If you wish to use
 265 .Bf -emphasis
 266 passive mode
 267 .Ef
 268 ftp in such transfers, set
 269 the variable
 270 .Bf -emphasis
 271 FTP_PASSIVE_MODE
 272 .Ef
 273 to some value in your environment.
 274 Otherwise, the more standard
 275 ACTIVE mode may be used.
 276 If
 277 .Nm
 278 consistently fails to fetch a package from a site known to work,
 279 it may be because you have a firewall that demands the usage of
 280 .Bf -emphasis
 281 passive mode
 282 .Ef
 283 ftp.
 284 .Sh TECHNICAL DETAILS
 285 The
 286 .Nm
 287 utility extracts each package's
 288 .Dq "packing list"
 289 into a special staging directory (see
 290 .Sx ENVIRONMENT ) ,
 291 parses it, and then runs
 292 through the following sequence to fully extract the contents of the package:
 293 .Bl -enum
 294 .It
 295 A check is made to determine if the package is already recorded as installed.
 296 If it is, installation is terminated.
 297 .It
 298 A check is made to determine if the package conflicts (from
 299 .Ic @conflicts
 300 directives, see
 301 .Xr pkg_create 1 )
 302 with an already installed package.
 303 If it is, installation is terminated.
 304 .It
 305 Scan all the package dependencies (from
 306 .Ic @pkgdep
 307 directives, see
 308 .Xr pkg_create 1 )
 309 are read from the packing list.
 310 If any of these required packages is not currently installed,
 311 an attempt is made to find and install it;
 312 if the missing package cannot be found or installed,
 313 the installation is terminated.
 314 .It
 315 Search for any
 316 .Ic @option
 317 directives which control how the package is added to the system.
 318 At the time of this writing, the only currently implemented option is
 319 .Ic @option Cm extract-in-place
 320 which will cause the package to be extracted directly into its
 321 prefix directory without moving through a staging area.
 322 .It
 323 If
 324 .Ic @option Cm extract-in-place
 325 is enabled, the package is now extracted directly into its
 326 final location, otherwise it is extracted into the staging area.
 327 .It
 328 If a requirements script
 329 .Pa +REQUIRE
 330 exists for the package (see the
 331 .Fl r
 332 flag of
 333 .Xr pkg_create 1 ) ,
 334 then execute it with the following arguments:
 335 .Pp
 336 .D1 Ar pkg-name Li INSTALL
 337 .Pp
 338 where
 339 .Ar pkg-name
 340 is the name of the package in question and the
 341 .Dq Li INSTALL
 342 keyword denotes this as an installation requirements check (useful if
 343 you want to have one script serving multiple functions).
 344 .It
 345 If a pre-install script
 346 .Pa +INSTALL
 347 exists for the package,
 348 it is then executed with the following arguments:
 349 .Pp
 350 .D1 Ar pkg-name Li PRE-INSTALL
 351 .Pp
 352 where
 353 .Ar pkg-name
 354 is the name of the package in question and
 355 .Dq Li PRE-INSTALL
 356 is a keyword denoting this as the preinstallation phase.
 357 .Pp
 358 .Sy Note :
 359 The
 360 .Dq Li PRE-INSTALL
 361 keyword will not appear if separate scripts for pre-install and post-install
 362 are given during package creation time (using the
 363 .Fl i
 364 and
 365 .Fl I
 366 flags to
 367 .Xr pkg_create 1 ) .
 368 .It
 369 If
 370 .Cm @option Cm extract-in-place
 371 is not used, then the packing list (this is the
 372 .Pa +CONTENTS
 373 file) is now used as a guide for moving (or copying, as necessary) files from
 374 the staging area into their final locations.
 375 .It
 376 If an mtree file
 377 .Pa +MTREE_DIRS
 378 exists for the package (see the
 379 .Fl m
 380 flag of
 381 .Xr pkg_create 1 ) ,
 382 then
 383 .Xr mtree 8
 384 is invoked as:
 385 .Pp
 386 .D1 Nm mtree Fl U f Pa +MTREE_DIRS Fl d e p Ar prefix
 387 .Pp
 388 where
 389 .Ar prefix
 390 is either the prefix specified with the
 391 .Fl p
 392 or
 393 .Fl P
 394 flag or,
 395 if neither flag was specified, the name of the first directory named by a
 396 .Ic @cwd
 397 directive within this package.
 398 .It
 399 If a post-install script
 400 .Pa +POST-INSTALL
 401 exists for the package,
 402 it is then executed with the following arguments:
 403 .Pp
 404 .D1 Ar pkg-name Li POST-INSTALL
 405 .Pp
 406 where
 407 .Ar pkg-name
 408 is the name of the package in question and
 409 .Dq Li POST-INSTALL
 410 is a keyword denoting this as the post-installation phase.
 411 .Pp
 412 .Sy Note :
 413 The
 414 .Dq Li POST-INSTALL
 415 keyword will not appear if separate scripts for pre-install and post-install
 416 are given during package creation time (using the
 417 .Fl i
 418 and
 419 .Fl I
 420 flags to
 421 .Xr pkg_create 1 ) .
 422 .Pp
 423 Reasoning behind passing keywords such as
 424 .Dq Li POST-INSTALL
 425 and
 426 .Dq Li PRE-INSTALL
 427 is that this allows you to write a single
 428 install
 429 script that does both
 430 .Dq before
 431 and
 432 .Dq after
 433 actions.
 434 But, separating the
 435 functionality is more advantageous and easier from a maintenance viewpoint.
 436 .It
 437 After installation is complete, a copy of the
 438 description
 439 .Pq Pa +DESC ,
 440 comment
 441 .Pq Pa +COMMENT ,
 442 pre-install script
 443 .Pq Pa +INSTALL ,
 444 post-install script
 445 .Pq Pa +POST-INSTALL ,
 446 deinstall script
 447 .Pq Pa +DEINSTALL ,
 448 post-deinstall script
 449 .Pq Pa +POST-DEINSTALL ,
 450 requirements script
 451 .Pq Pa +REQUIRE ,
 452 display
 453 .Pq Pa +DISPLAY ,
 454 mtree
 455 .Pq Pa +MTREE_DIRS ,
 456 and packing list
 457 .Pq Pa +CONTENTS
 458 files are copied into
 459 .Pa /var/db/pkg/ Ns Aq Ar pkg-name
 460 for subsequent possible use by
 461 .Xr pkg_delete 1 .
 462 Any package dependencies are recorded in the other packages'
 463 .Pa /var/db/pkg/ Ns Ao Ar other-pkg Ac Ns Pa /+REQUIRED_BY
 464 file
 465 (if the environment variable
 466 .Ev PKG_DBDIR
 467 is set, this overrides the
 468 .Pa /var/db/pkg/
 469 path shown above).
 470 .It
 471 Finally, the staging area is deleted and the program terminates.
 472 .El
 473 .Pp
 474 All the scripts are called with the environment variable
 475 .Ev PKG_PREFIX
 476 set to the installation prefix (see the
 477 .Fl p
 478 and
 479 .Fl P
 480 options above).
 481 This allows a package author to write a script
 482 that reliably performs some action on the directory where the package
 483 is installed, even if the user might change it with the
 484 .Fl p
 485 or
 486 .Fl P
 487 flags to
 488 .Nm .
 489 .Sh ENVIRONMENT
 490 The value of the
 491 .Ev PKG_PATH
 492 is used if a given package cannot be found.
 493 The environment variable
 494 should be a series of entries separated by colons.
 495 Each entry
 496 consists of a directory name.
 497 The current directory may be indicated
 498 implicitly by an empty directory name, or explicitly by a single
 499 period.
 500 .Pp
 501 The environment variable
 502 .Ev PKG_DBDIR
 503 specifies an alternative location for the installed package database,
 504 default location is
 505 .Pa /var/db/pkg .
 506 .Pp
 507 The environment variables
 508 .Ev PKG_TMPDIR
 509 and
 510 .Ev TMPDIR ,
 511 in that order, are taken to name temporary directories where
 512 .Nm
 513 will attempt to create its staging area in.
 514 If these variables are not present or if the directories named lack
 515 sufficient space, then
 516 .Nm
 517 will use the first of
 518 .Pa /var/tmp ,
 519 .Pa /tmp
 520 or
 521 .Pa /usr/tmp
 522 with sufficient space.
 523 .Pp
 524 The environment variable
 525 .Ev PACKAGEROOT
 526 specifies an alternate location for
 527 .Nm
 528 to fetch from.
 529 The fetch URL is built using this environment variable and the automatic
 530 directory logic that
 531 .Nm
 532 uses when the
 533 .Fl r
 534 option is invoked.
 535 An example setting would be
 536 .Qq Li ftp://ftp3.FreeBSD.org .
 537 .Pp
 538 The environment variable
 539 .Ev PACKAGESITE
 540 specifies an alternate location for
 541 .Nm
 542 to fetch from.
 543 This variable subverts the automatic directory logic
 544 that
 545 .Nm
 546 uses when the
 547 .Fl r
 548 option is invoked.
 549 Thus it should be a complete URL to the remote package file(s).
 550 .Pp
 551 The environment variable
 552 .Ev PKGDIR
 553 specifies an alternative location to save downloaded packages to when
 554 .Fl K
 555 option is used.
 556 .Pp
 557 The environment variable
 558 .Ev PACKAGESUFFIX
 559 specifies an alternative file extension to use when fetching remote
 560 packages. Default is .tbz
 561 .Sh FILES
 562 .Bl -tag -width /var/db/pkg -compact
 563 .It Pa /var/tmp
 564 Temporary directory for creating the staging area, if environmental variables
 565 .Ev PKG_TMPDIR
 566 or
 567 .Ev TMPDIR
 568 do not point to a suitable directory.
 569 .It Pa /tmp
 570 Next choice if
 571 .Pa /var/tmp
 572 does not exist or has insufficient space.
 573 .It Pa /usr/tmp
 574 Last choice if
 575 .Pa /var/tmp
 576 and
 577 .Pa /tmp
 578 are not suitable for creating the staging area.
 579 .It Pa /var/db/pkg
 580 Default location of the installed package database.
 581 .El
 582 .Sh SEE ALSO
 583 .Xr pkg_create 1 ,
 584 .Xr pkg_delete 1 ,
 585 .Xr pkg_info 1 ,
 586 .Xr pkg_version 1 ,
 587 .Xr mktemp 3 ,
 588 .Xr sysconf 3 ,
 589 .Xr mtree 8
 590 .Sh AUTHORS
 591 .An Jordan Hubbard
 592 .Sh CONTRIBUTORS
 593 .An John Kohl Aq jtk@rational.com
 594 .Sh BUGS
 595 Hard links between files in a distribution are only preserved if either
 596 (1) the staging area is on the same file system as the target directory of
 597 all the links to the file, or (2) all the links to the file are bracketed by
 598 .Cm @cwd
 599 directives in the contents file,
 600 .Em and
 601 the link names are extracted with a single
 602 .Cm tar
 603 command (not split between
 604 invocations due to exec argument-space limitations--this depends on the
 605 value returned by
 606 .Fn sysconf _SC_ARG_MAX ) .
 607 .Pp
 608 Sure to be others.