2 .\" FreeBSD install - a package for the installation and maintainance
3 .\" of non-core utilities.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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.
23 .Nd a utility for installing software package distributions
31 .Ar pkg-name Op Ar pkg-name ...
35 command is used to extract packages that have been previously created
43 command may execute scripts or programs contained within a package file,
44 your system may be susceptible to
47 attacks from miscreants who create dangerous package files.
49 You are advised to verify the competence and identity of those who
50 provide installable package files.
51 For extra protection, use the
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.
56 attention to any +INSTALL, +POST-INSTALL, +DEINSTALL, +POST-DEINSTALL,
57 +REQUIRE or +MTREE_DIRS files, and inspect the +CONTENTS file for
65 directives, and/or use the
67 command to examine the package file.
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.
79 If the packages are not found in the current
82 will search them in each directory named by
85 Turn on verbose output.
87 Keep any downloaded package in
89 if it is defined or in current directory by default.
91 If any installation scripts (pre-install or post-install) exist for a given
92 package, do not execute them.
94 Do not actually install a package, just report the steps that
95 would be taken if it was.
97 Do not record the installation of a package.
99 that you cannot deinstall it later, so only use this option if
100 you know what you are doing!
102 Use the remote fetching feature.
103 This will determine the appropriate
104 objformat and release and then fetch and install the package.
106 Force installation to proceed even if prerequisite packages are not
107 installed or the requirements script fails.
110 will still try to find and auto-install missing prerequisite packages,
111 a failure to find one will not be fatal.
113 Already installed packages are not an error.
117 as the directory in which to extract files from a package.
118 If a package has set its default directory, it will be overridden
120 Note that only the first
122 directive will be replaced, since
124 has no way of knowing which directory settings are relative and
126 It is rare in any case to see more than one
127 directory transition made, but when such does happen and you wish
128 to have control over *all* directory transitions, then you
129 may then wish to look into the use of
140 flag appears after any
142 flag on the command line, it overrides its effect, causing
150 option, except that the given
152 is also used recursively for the dependency packages, if any.
155 flag appears after any
157 flag on the command line, it overrides its effect, causing
169 By default, this is the string
170 .Pa /var/tmp/instmp.XXXXXX ,
171 but it may be necessary to override it in the situation where
174 directory is limited.
175 Be sure to leave some number of `X' characters
178 to fill in with a unique ID.
180 You can get a performance boost by setting the staging area
182 to reside on the same disk partition as target directories for package
183 file installation; often this is
189 This is a very specialized mode for running
191 and is meant to be run in conjunction with
194 When run in this mode,
196 does no work beyond extracting the package into a temporary staging
199 option), reading in the packing list, and then dumping it (prefaced by
200 the current staging area) to stdout where it may be filtered by a
203 When used in conjunction with
205 mode, it allows you to make radical changes to the package structure
206 before acting on its contents.
211 This is a very specialized mode for running
213 and is meant to be run in conjunction with
216 When run in this mode,
218 expects the release contents to be already extracted and waiting
219 in the staging area, the location of which is read as a string
221 The complete packing list is also read from stdin,
222 and the contents then acted on as normal.
223 .It Fl C Ar chrootdir
224 Before doing any operations,
228 directory so that all package files, and the package database, are
233 needs to be a fairly complete file system, including everything normally
237 This flag was added to help support operations done by
239 and is not expected to be useful for much else.
242 is properly configured and cannot be modified by normal users,
243 versions of commands like
252 arguments may be specified, each being either a file containing the
253 package (these usually end with a
256 URL pointing at a file available on an ftp site.
258 extract files directly from their anonymous ftp locations (e.g.\&
260 .Li ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/shells/bash-1.14.7.tbz ) .
261 Note: If you wish to use
265 ftp in such transfers, set
270 to some value in your environment.
271 Otherwise, the more standard
272 ACTIVE mode may be used.
275 consistently fails to fetch a package from a site known to work,
276 it may be because you have a firewall that demands the usage of
281 .Sh TECHNICAL DETAILS
284 utility extracts each package's "packing list" into a special staging
285 directory in /tmp (or $PKG_TMPDIR if set), parses it, and then runs
286 through the following sequence to fully extract the contents of the package:
289 A check is made to determine if the package is already recorded as installed.
290 If it is, installation is terminated.
292 A check is made to determine if the package conflicts (from
296 with an already-installed package.
297 If it is, installation is terminated.
299 Scan all the package dependencies (from
303 are read from the packing list.
304 If any of these required packages is not currently installed,
305 an attempt is made to find and install it;
306 if the missing package cannot be found or installed,
307 the installation is terminated.
311 directives which control how the package is added to the system.
312 At the time of this writing, the only currently implemented option is
313 .Cm @option extract-in-place
314 which will cause the package to be extracted directly into its
315 prefix directory without moving through a staging area in
319 .Cm @option extract-in-place
320 is enabled, the package is now extracted directly into its
321 final location, otherwise it is extracted into the staging area.
323 If the package contains a
327 then execute it with the following arguments:
328 .Bd -ragged -offset indent -compact
334 is the name of the package in question and the
336 keyword denotes this as an installation requirements check (useful if
337 you want to have one script serving multiple functions).
341 script exists for the package, it is then executed with the following
343 .Bd -ragged -offset indent -compact
351 is the name of the package in question and
353 is a keyword denoting this as the preinstallation phase.
358 keyword will not appear if separate scripts for pre-install and post-install
359 are given during package creation time (using the
367 .Cm @option extract-in-place
368 is not used, then the packing list (this is the
370 file) is now used as a guide for moving (or copying, as necessary) files from
371 the staging area into their final locations.
373 If the package contains an
377 then mtree is invoked as:
378 .Bd -ragged -offset indent -compact
390 is either the prefix specified with the
395 if neither flag was specified, the name of the first directory named by a
397 directive within this package.
401 script exists for the package, it is then executed as
402 .Bd -ragged -offset indent -compact
409 is the name of the package in question and
411 is a keyword denoting this as the post-installation phase.
416 keyword will not appear if separate scripts for pre-install and post-install
417 are given during package creation time (using the
424 Reasoning behind passing keywords such as
428 is that this allows you to write a single
430 script that does both
434 functionality is more advantageous and easier from a maintenance viewpoint.
436 After installation is complete, a copy of the packing list,
438 script, description, and display files are copied into
439 .Pa /var/db/pkg/<pkg-name>
440 for subsequent possible use by
442 Any package dependencies are recorded in the other packages'
443 .Pa /var/db/pkg/<other-pkg>/+REQUIRED_BY
445 (if the environment variable PKG_DBDIR is set, this overrides the
449 Finally, the staging area is deleted and the program terminates.
452 All the scripts are called with the environment variable
454 set to the installation prefix (see the
459 This allows a package author to write a script
460 that reliably performs some action on the directory where the package
461 is installed, even if the user might change it with the
470 is used if a given package cannot be found.
471 The environment variable
472 should be a series of entries separated by colons.
474 consists of a directory name.
475 The current directory may be indicated
476 implicitly by an empty directory name, or explicitly by a single
479 The environment variable
481 specifies an alternative location for the installed package database,
485 The environment variables
489 in that order, are taken to name temporary directories where
491 will attempt to create its staging area in.
492 If these variables are not present or if the directories named lack
493 sufficient space, then
495 will use the first of
500 with sufficient space.
502 The environment variable
504 specifies an alternate location for
507 The fetch URL is built using this environment variable and the automatic
513 An example setting would be
514 .Qq Li ftp://ftp3.FreeBSD.org .
516 The environment variable
518 specifies an alternate location for
521 This variable subverts the automatic directory logic
527 Thus it should be a complete URL to the remote package file(s).
529 The environment variable
531 specifies an alternative location to save downloaded packages to when
535 .Bl -tag -width /var/db/pkg -compact
537 Temporary directory for creating the staging area, if environmental variables
541 do not point to a suitable directory.
545 does not exist or has insufficient space.
551 are not suitable for creating the staging area.
553 Default location of the installed package database.
566 .An John Kohl Aq jtk@rational.com
568 Hard links between files in a distribution are only preserved if either
569 (1) the staging area is on the same file system as the target directory of
570 all the links to the file, or (2) all the links to the file are bracketed by
572 directives in the contents file,
574 the link names are extracted with a single
576 command (not split between
577 invocations due to exec argument-space limitations--this depends on the
579 .Fn sysconf _SC_ARG_MAX ) .