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