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 Install the package without fetching and installing
94 If any installation scripts (pre-install or post-install) exist for a given
95 package, do not execute them.
97 Do not actually install a package, just report the steps that
98 would be taken if it was.
100 Do not record the installation of a package.
102 that you cannot deinstall it later, so only use this option if
103 you know what you are doing!
105 Use the remote fetching feature.
106 This will determine the appropriate
107 objformat and release and then fetch and install the package.
109 Force installation to proceed even if prerequisite packages are not
110 installed or the requirements script fails.
113 will still try to find and auto-install missing prerequisite packages,
114 a failure to find one will not be fatal.
116 Already installed packages are not an error.
117 .It Fl p , -prefix 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
123 Note that only the first
125 directive will be replaced, since
127 has no way of knowing which directory settings are relative and
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
143 flag appears after any
145 flag on the command line, it overrides its effect, causing
153 option, except that the given
155 is also used recursively for the dependency packages, if any.
158 flag appears after any
160 flag on the command line, it overrides its effect, causing
165 .It Fl t , -template Ar template
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
177 directory is limited.
178 Be sure to leave some number of `X' characters
181 to fill in with a unique ID.
183 You can get a performance boost by setting the staging area
185 to reside on the same disk partition as target directories for package
186 file installation; often this is
192 This is a very specialized mode for running
194 and is meant to be run in conjunction with
197 When run in this mode,
199 does no work beyond extracting the package into a temporary staging
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
206 When used in conjunction with
208 mode, it allows you to make radical changes to the package structure
209 before acting on its contents.
214 This is a very specialized mode for running
216 and is meant to be run in conjunction with
219 When run in this mode,
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
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,
231 directory so that all package files, and the package database, are
236 needs to be a fairly complete file system, including everything normally
240 This flag was added to help support operations done by
242 and is not expected to be useful for much else.
245 is properly configured and cannot be modified by normal users,
246 versions of commands like
255 arguments may be specified, each being either a file containing the
256 package (these usually end with a
259 URL pointing at a file available on an ftp site.
261 extract files directly from their anonymous ftp locations (e.g.\&
263 .Li ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/shells/bash-1.14.7.tbz ) .
264 Note: If you wish to use
268 ftp in such transfers, set
273 to some value in your environment.
274 Otherwise, the more standard
275 ACTIVE mode may be used.
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
284 .Sh TECHNICAL DETAILS
287 utility extracts each package's
289 into a special staging directory (see
291 parses it, and then runs
292 through the following sequence to fully extract the contents of the package:
295 A check is made to determine if the package is already recorded as installed.
296 If it is, installation is terminated.
298 A check is made to determine if the package conflicts (from
302 with an already installed package.
303 If it is, installation is terminated.
305 Scan all the package dependencies (from
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.
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.
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.
328 If a requirements script
330 exists for the package (see the
334 then execute it with the following arguments:
336 .D1 Ar pkg-name Li INSTALL
340 is the name of the package in question and the
342 keyword denotes this as an installation requirements check (useful if
343 you want to have one script serving multiple functions).
345 If a pre-install script
347 exists for the package,
348 it is then executed with the following arguments:
350 .D1 Ar pkg-name Li PRE-INSTALL
354 is the name of the package in question and
356 is a keyword denoting this as the preinstallation phase.
361 keyword will not appear if separate scripts for pre-install and post-install
362 are given during package creation time (using the
370 .Cm @option Cm extract-in-place
371 is not used, then the packing list (this is the
373 file) is now used as a guide for moving (or copying, as necessary) files from
374 the staging area into their final locations.
378 exists for the package (see the
386 .D1 Nm mtree Fl U f Pa +MTREE_DIRS Fl d e p Ar prefix
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.
399 If a post-install script
401 exists for the package,
402 it is then executed with the following arguments:
404 .D1 Ar pkg-name Li POST-INSTALL
408 is the name of the package in question and
410 is a keyword denoting this as the post-installation phase.
415 keyword will not appear if separate scripts for pre-install and post-install
416 are given during package creation time (using the
423 Reasoning behind passing keywords such as
427 is that this allows you to write a single
429 script that does both
435 functionality is more advantageous and easier from a maintenance viewpoint.
437 After installation is complete, a copy of the
445 .Pq Pa +POST-INSTALL ,
448 post-deinstall script
449 .Pq Pa +POST-DEINSTALL ,
458 files are copied into
459 .Pa /var/db/pkg/ Ns Aq Ar pkg-name
460 for subsequent possible use by
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
465 (if the environment variable
467 is set, this overrides the
471 Finally, the staging area is deleted and the program terminates.
474 All the scripts are called with the environment variable
476 set to the installation prefix (see the
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
492 is used if a given package cannot be found.
493 The environment variable
494 should be a series of entries separated by colons.
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
501 The environment variable
503 specifies an alternative location for the installed package database,
507 The environment variables
511 in that order, are taken to name temporary directories where
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
517 will use the first of
522 with sufficient space.
524 The environment variable
526 specifies an alternate location for
529 The fetch URL is built using this environment variable and the automatic
535 An example setting would be
536 .Qq Li ftp://ftp3.FreeBSD.org .
538 The environment variable
540 specifies an alternate location for
543 This variable subverts the automatic directory logic
549 Thus it should be a complete URL to the remote package file(s).
551 The environment variable
553 specifies an alternative location to save downloaded packages to when
557 .Bl -tag -width /var/db/pkg -compact
559 Temporary directory for creating the staging area, if environmental variables
563 do not point to a suitable directory.
567 does not exist or has insufficient space.
573 are not suitable for creating the staging area.
575 Default location of the installed package database.
588 .An John Kohl Aq jtk@rational.com
590 Hard links between files in a distribution are only preserved if either
591 (1) the staging area is on the same file system as the target directory of
592 all the links to the file, or (2) all the links to the file are bracketed by
594 directives in the contents file,
596 the link names are extracted with a single
598 command (not split between
599 invocations due to exec argument-space limitations--this depends on the
601 .Fn sysconf _SC_ARG_MAX ) .