1 .\" $NetBSD: pkg_add.1,v 1.39 2010/01/20 22:34:47 jmmv Exp $
3 .\" FreeBSD install - a package for the installation and maintenance
4 .\" of non-core utilities.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
25 .Nd a utility for installing and upgrading software package distributions
35 .Ar Oo Oo Li ftp|http Oc Ns Li :// Ns Oo Ar user Oc Ns \
36 Oo Li \&: Ns Ar password Oc \
37 Ns Li @ Oc Ns Ar host Ns Oo Li \&: Ns Ar port Oc Ns \
38 Oo Li / Ns Ar path/ Oc Ns Ar pkg-name ...
42 command is used to extract and upgrade packages that have been
43 previously created with the
46 Packages are prepared collections of pre-built binaries, documentation,
47 configurations, installation instructions and/or other files.
49 can recursively install other packages that the current package
50 depends on or requires from both local disk and via FTP or HTTP.
55 command may execute scripts or programs contained within a package file,
56 your system may be susceptible to
59 attacks from miscreants who create dangerous package files.
61 You are advised to verify the competence and identity of those who
62 provide installable package files.
63 For extra protection, use the digital signatures provided where possible
65 .Xr pkg_install.conf 5 ) ,
68 to extract the package file, and inspect its contents and scripts
69 to ensure it poses no danger to your system's integrity.
70 Pay particular attention to any
74 files, and inspect the
84 directives, and/or use the
86 command to examine the package file.
89 The following command line arguments are supported:
90 .Bl -tag -width indent
91 .It Ar pkg-name [ ... ]
92 The named packages are installed.
96 as full URL or path name without any wildcard processing.
99 will try to match packages using wildcard processing.
100 If that fails as well and
102 does not contain any /, the entries of the
104 variable are searched using the wildcard processing rules.
106 Mark package as installed automatically, as dependency of another
109 .Dl Ic pkg_admin set automatic=YES
110 to mark packages this way after installation, and
111 .Dl Ic pkg_admin unset automatic
115 a package without specifying
117 after it had already been automatically installed, the mark is
120 Force installation to proceed even if prerequisite packages are not
121 installed or the install script fails.
124 will still try to find and auto-install missing prerequisite packages,
125 a failure to find one will not be fatal.
126 This flag also overrides the fatal error when the operating system or
127 architecture the package was built on differ from that of the host.
129 If an installation script exists for a given package, do not execute it.
130 .It Fl K Ar pkg_dbdir
133 as the package database directory.
136 section below for details on how the default value is calculated.
138 Don't add the package to any views after installation.
140 Override the machine architecture returned by uname with
143 Don't actually install a package, just report the steps that
144 would be taken if it was.
146 Prefix all file and directory names with
148 For packages without install scripts this has the same behavior as
153 as the directory in which to extract files from a package.
154 If a package has set its default directory, it will be overridden
156 Note that only the first
158 directive will be replaced, since
160 has no way of knowing which directory settings are relative and
162 Only one directory transition is supported and the second one is expected to go
166 Do not record the installation of a package.
169 This means that you cannot deinstall it later, so only use this option if
170 you know what you are doing!
172 If the package that's being installed is already installed,
173 an update is performed.
174 It is currently not possible to update to an identical version.
175 If this is specified twice, then any dependent packages that are
176 too old will also be updated to fulfill the dependency.
177 See below for a more detailed description of the process.
179 Print version number and exit.
181 Turn on verbose output.
185 as the base directory for the managed views.
190 This value also may be set from the
192 environment variable.
196 to which packages should be added after installation.
201 This value also may be set from the
203 environment variable.
208 arguments may be specified, each being either a file containing the
209 package (these usually ending with the
212 URL pointing at a file available on an ftp or web site.
213 Thus you may extract files directly from their anonymous ftp or WWW
216 ftp://ftp.NetBSD.org/pub/pkgsrc/packages/NetBSD/i386/3.1_2007Q2/shells/bash-3.2.9.tgz
219 http://www.example.org/packages/screen-4.0.tbz).
220 Note: For ftp transfers, if you wish to use
224 ftp in such transfers, set the variable
228 to some value in your environment.
229 Otherwise, the more standard ACTIVE mode may be used.
232 consistently fails to fetch a package from a site known to work,
233 it may be because you have a firewall that demands the usage of
238 .Sh TECHNICAL DETAILS
240 extracts each package's meta data (including the
242 to memory and then runs through the following sequence to fully extract
243 the contents of the package:
244 .Bl -enum -offset indent
246 A check is made to determine if the package or another version of it
247 is already recorded as installed.
249 installation is terminated if the
255 option is given, it's assumed the package should be replaced by the
257 Before doing so, all packages that depend on the
258 pkg being upgraded are checked if they also work with the new version.
259 If that test is successful, replacing is prepared by moving an existing
261 file aside (if it exists), and running
263 on the installed package.
264 Installation then proceeds as if the package
265 was not installed, and restores the
269 The package build information is extracted from the
271 file and compared against the result of
273 If the operating system or architecture of the package differ from
274 that of the host, installation is aborted.
275 This behavior is overridable with the
279 The package build information from
282 .Ev USE_ABI_DEPENDS=NO
284 .Ev IGNORE_RECOMMENDED ) .
285 If the package was built with ABI dependency recommendations ignored,
286 a warning will be issued.
288 A check is made to determine if the package conflicts (from
292 with an already recorded as installed package or if an installed package
293 conflicts with the package.
294 If it is, installation is terminated.
296 The file list of the package is compared to the file lists of the
298 If there is any overlap, the installation is terminated.
300 All package dependencies (from
304 are read from the packing list.
305 If any of these required packages are not currently installed,
306 an attempt is made to find and install it;
307 if the missing package cannot be found or installed,
308 the installation is terminated.
311 option was specified twice, any required packages that are installed,
312 but which have a version number that is considered to be too old,
314 The dependent packages are found according to the normal
318 If the package contains an
320 script, it is executed with the following arguments:
321 .Bl -tag -width indentindent
323 The name of the package being installed.
325 Keyword denoting that the script is to perform any actions needed before
326 the package is installed.
331 script exits with a non-zero status code, the installation is terminated.
333 The files from the file list are extracted to the chosen prefix.
337 script exists for the package, it is executed with the following arguments:
338 .Bl -tag -width indentindent
340 The name of the package being installed.
342 Keyword denoting that the script is to perform any actions needed
343 after the package has been installed.
346 After installation is complete, a copy of the packing list,
348 script, description, and display files are copied into
349 .Pa /var/db/pkg/\*[Lt]pkg-name\*[Gt]
350 for subsequent possible use by
352 Any package dependencies are recorded in the other packages'
353 .Pa /var/db/pkg/\*[Lt]other-pkg\*[Gt]/+REQUIRED_BY
355 (if an alternate package database directory is specified, then it
360 If the package is a depoted package, then add it to the default view.
362 Finally, if we were upgrading a package, any
364 file that was moved aside before upgrading was started is now moved
370 script is called with the environment variable
372 set to the installation prefix (see the
375 This allows a package author to write a script
376 that reliably performs some action on the directory where the package
377 is installed, even if the user might change it with the
381 The scripts are also called with the
383 environment variable set to the location of the
385 meta-data files, and with the
386 .Ev PKG_REFCOUNT_DBDIR
387 environment variable set to the location of the package reference counts
397 .Bl -tag -width PKG_TMPDIR
399 This is the location of the
401 directory in which all the views are managed.
409 flag isn't given, then the value of the
411 variable overrides the
412 .Xr pkg_install.conf 5
413 variable of the same name.
414 If all of this fails to locate a value, then it typically defaults to
419 variable overrides the
420 .Xr pkg_install.conf 5
421 variable of the same name.
422 It is used if a given package can't be found, it's usually set to
423 .Pa /usr/pkgsrc/packages/All .
424 The environment variable
425 should be a series of entries separated by semicolons.
426 Each entry consists of a directory name or URL.
427 The current directory may be indicated implicitly by an empty directory
428 name, or explicitly by a single period.
429 .It Ev PKG_REFCOUNT_DBDIR
430 Location of the package reference counts database directory.
431 The default location is the path to the package database directory with
433 appended to the path, e.g.
434 .Pa /var/db/pkg.refcount .
436 The default view can be specified in the
438 environment variable.
443 will try to install binary packages listed in dependencies list.
445 You can specify a compiled binary package explicitly on the command line.
447 # pkg_add /usr/pkgsrc/packages/All/tcsh-6.14.00.tgz
450 If you omit the version number,
452 will install the latest version available.
456 emits more messages to terminal.
458 # pkg_add -v /usr/pkgsrc/packages/All/unzip
461 You can grab a compiled binary package from remote location by specifying
463 The URL can be put into an environment variable,
466 # pkg_add -v ftp://ftp.NetBSD.org/pub/pkgsrc/packages/NetBSD/i386/3.1_2007Q2/All/firefox-2.0.0.4.tgz
468 # export PKG_PATH=ftp://ftp.NetBSD.org/pub/pkgsrc/packages/NetBSD/i386/3.1_2007Q2/All
472 Over time, as problems are found in packages, they will be moved
475 subdirectory into the
478 If you want to accept vulnerable packages by default
479 (and know what you are doing),
486 # export PKG_PATH="ftp://ftp.NetBSD.org/pub/pkgsrc/packages/NetBSD/i386/3.1_2007Q2/All/;ftp://ftp.NetBSD.org/pub/pkgsrc/packages/NetBSD/i386/3.1_2007Q2/vulnerable/"
489 (The quotes are needed because semicolon
491 is a shell meta-character.)
492 If you do this, consider using the audit capabilities in
494 and running it after every
496 .Sh CONFIGURATION VARIABLES
497 The following variables change the behavior of
500 .Xr pkg_install.conf 5 :
501 .Bl -tag -compact -offset indent -width CERTIFICATE_ANCHOR_PKGS
503 .It Ev CHECK_VULNERABILITIES
504 .It Ev CERTIFICATE_ANCHOR_PKGS
505 .It Ev CERTIFICATE_CHAIN
506 .It Ev VERIFIED_INSTALLATION
516 .Xr pkg_install.conf 5 ,
519 .Bl -tag -width indent -compact
521 Initial work and ongoing development.
527 wildcard dependency processing, pkgdb, upgrading, etc.
530 .It Joerg Sonnenberger
531 Rewrote most of the code base to work without external commands.
534 Package upgrading needs a lot more work to be really universal.