6324 Add an `ndp' tool for manipulating the neighbors table
[illumos-gate.git] / usr / src / man / man1m / pkgadd.1m
blob2bae037332c55158decfa459cdd21dc366552fd6
1 '\" te
2 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved
3 .\" Copyright 1989 AT&T
4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
7 .TH PKGADD 1M "Oct 30, 2007"
8 .SH NAME
9 pkgadd \- transfer software packages to the system
10 .SH SYNOPSIS
11 .LP
12 .nf
13 \fBpkgadd\fR [\fB-nv\fR] [\fB-a\fR \fIadmin\fR] [\fB-G\fR] [\fB-x\fR \fIproxy\fR]
14      [ [\fB-M\fR] \fB-R\fR \fIroot_path\fR] [\fB-r\fR \fIresponse\fR] [\fB-k\fR \fIkeystore\fR]
15      [\fB-P\fR \fIpasswd\fR] [\fB-V\fR \fIfs_file\fR]
16      [\fB-d\fR \fIdevice\fR | \fB-d\fR \fIdatastream\fR \fIpkginst\fR | all]
17      [\fIpkginst\fR | \fB-Y\fR \fIcategory\fR [\fI, category\fR]...]
18 .fi
20 .LP
21 .nf
22 \fBpkgadd\fR \fB-s\fR [\fB-d\fR \fIdevice\fR | \fB-d\fR \fIdatastream\fR \fIpkginst\fR | all]
23      [\fIpkginst\fR | \fB-Y\fR \fIcategory\fR [\fI, category\fR]...]
24 .fi
26 .SH DESCRIPTION
27 .sp
28 .LP
29 \fBpkgadd\fR transfers the contents of a software package from the distribution
30 medium or directory to install it onto the system. Used without the \fB-d\fR
31 \fIdevice\fR source specifier, \fBpkgadd\fR looks in the default spool
32 directory (\fB/var/spool/pkg\fR) for the package. Used with the \fB-s\fR
33 option, it writes the package to a spool directory instead of installing it.
34 .sp
35 .LP
36 The \fBpkgadd\fR utility requires an amount of temporary space the size of the
37 package that is being installed. \fBpkgadd\fR determines which temporary
38 directory to use by checking for the existance of the \fB$TMPDIR\fR environment
39 variable. If \fB$TMPDIR\fR is not defined, \fBpkgadd\fR uses \fBP_tmpdir\fR
40 from \fBstdio.h\fR. \fBP_tmpdir\fR has a default of \fB/var/tmp/\fR.
41 .sp
42 .LP
43 Certain unbundled and third-party packages are no longer entirely compatible
44 with the latest version of \fBpkgadd\fR. These packages require user
45 interaction throughout the installation and not just at the very beginning, or
46 require that their request scripts be run as the root user.
47 .sp
48 .LP
49 To install these older packages (released prior to Solaris 2.4), set the
50 following environment variable: \fBNONABI_SCRIPTS=TRUE\fR
51 .sp
52 .LP
53 As long as this environment variable is set, \fBpkgadd\fR permits keyboard
54 interaction throughout the installation and package request scripts are run as
55 \fBroot\fR.
56 .sp
57 .LP
58 If you have package request scripts that require running as user \fBroot\fR
59 (instead of \fBnoaccess\fR [the default] or user \fBinstall\fR), use the
60 \fBrscript_alt\fR parameter in the \fBadmin\fR(4) file to make an appropriate
61 selection. See \fBadmin\fR(4).
62 .sp
63 .LP
64 Note that, in Solaris 8 and Solaris 9, the default user when running a request
65 script was either \fBroot\fR or \fBnobody\fR, depending on the operating
66 system's patch level. In the current release, the default user is
67 \fBnoaccess\fR.
68 .sp
69 .LP
70 When running \fBpkgadd\fR in the global zone (see \fBzones\fR(5)), a package
71 that contains a request script (see \fBpkgask\fR(1M)) is added only to the
72 global zone. The package is not propagated to any current or
73 yet-to-be-installed non-global zone. This behavior mimics the effect of the
74 \fB-G\fR option, described below.
75 .sp
76 .LP
77 Package commands are \fBlargefile\fR(5)-aware. They handle files larger than 2
78 GB in the same way they handle smaller files. In their current implementations,
79 \fBpkgadd\fR, \fBpkgtrans\fR(1) and other package commands can process a
80 datastream of  up to 4 GB.
81 .sp
82 .LP
83 The \fB-d\fR, \fB-Y\fR, and \fIpkginst\fR arguments shown in the SYNOPSIS are
84 described under OPERANDS, following OPTIONS.
85 .SH OPTIONS
86 .sp
87 .LP
88 The supported options are described as follows. The \fB-d\fR \fIdevice\fR
89 source specifier is described under OPERANDS, below.
90 .sp
91 .ne 2
92 .na
93 \fB\fB\fR\fB-a\fR \fIadmin\fR\fR
94 .ad
95 .sp .6
96 .RS 4n
97 Define an installation administration file, \fIadmin\fR, to be used in place of
98 the default administration file. The token \fBnone\fR overrides the use of any
99 \fIadmin\fR file, and thus forces interaction with the user. Unless a full path
100 name is given, \fBpkgadd\fR first looks in the current working directory for
101 the administration file. If the specified administration file is not in the
102 current working directory, \fBpkgadd\fR looks in the
103 \fB/var/sadm/install/admin\fR directory for the administration file.
107 .ne 2
109 \fB\fB-G\fR\fR
111 .sp .6
112 .RS 4n
113 Add package(s) in the current zone only. When used in the global zone, the
114 package is added to the global zone only and is not propagated to any existing
115 or yet-to-be-created non-global zone. When used in a non-global zone, the
116 package(s) are added to the non-global zone only.
118 This option causes package installation to fail if, in the \fBpkginfo\fR file
119 for a package, \fBSUNW_PKG_ALLZONES\fR is set to true. See \fBpkginfo\fR(4).
123 .ne 2
125 \fB\fB-k\fR \fIkeystore\fR\fR
127 .sp .6
128 .RS 4n
129 Use \fIkeystore\fR as the location from which to get trusted certificate
130 authority certificates when verifying digital signatures found in packages. If
131 no keystore is specified, then the default keystore locations are searched for
132 valid trusted certificates. See \fBKEYSTORE LOCATIONS\fR for more information.
136 .ne 2
138 \fB\fB-M\fR\fR
140 .sp .6
141 .RS 4n
142 Instruct \fBpkgadd\fR not to use the \fB$\fR\fIroot_path\fR\fB/etc/vfstab\fR
143 file for determining the client's mount points. This option assumes the mount
144 points are correct on the server and it behaves consistently with Solaris 2.5
145 and earlier releases.
149 .ne 2
151 \fB\fB-n\fR\fR
153 .sp .6
154 .RS 4n
155 Installation occurs in non-interactive mode. Suppress output of the list of
156 installed files. The default mode is interactive.
160 .ne 2
162 \fB\fB-P\fR \fIpasswd\fR\fR
164 .sp .6
165 .RS 4n
166 Password to use to decrypt keystore specified with \fB-k\fR, if required. See
167 \fBPASS PHRASE ARGUMENTS\fR for more information about the format of this
168 option's argument.
172 .ne 2
174 \fB\fB\fR\fB-r\fR \fIresponse\fR\fR
176 .sp .6
177 .RS 4n
178 Identify a file or directory which contains output from a previous
179 \fBpkgask\fR(1M) session. This file supplies the interaction responses that
180 would be requested by the package in interactive mode. \fIresponse\fR must be a
181 full pathname.
185 .ne 2
187 \fB\fB-R\fR \fIroot_path\fR\fR
189 .sp .6
190 .RS 4n
191 Define the full path name of a directory to use as the \fIroot_path\fR. All
192 files, including package system information files, are relocated to a directory
193 tree starting in the specified \fIroot_path\fR. The \fIroot_path\fR may be
194 specified when installing to a client from a server (for example,
195 \fB/export/root/client1\fR).
197 Note -
199 .RS 2
200 The root file system of any non-global zones must not be referenced with the
201 \fB-R\fR option. Doing so might damage the global zone's file system, might
202 compromise the security of the global zone, and might damage the non-global
203 zone's file system. See \fBzones\fR(5).
208 .ne 2
210 \fB\fB\fR\fB-s\fR \fIspool\fR\fR
212 .sp .6
213 .RS 4n
214 Write the package into the directory \fIspool\fR instead of installing it.
218 .ne 2
220 \fB\fB-v\fR\fR
222 .sp .6
223 .RS 4n
224 Trace all of the scripts that get executed by \fBpkgadd\fR, located in the
225 \fIpkginst\fR\fB/install\fR directory. This option is used for debugging the
226 procedural and non-procedural scripts.
230 .ne 2
232 \fB\fB-V\fR \fIfs_file\fR\fR
234 .sp .6
235 .RS 4n
236 Specify an alternative \fIfs_file\fR to map the client's file systems. For
237 example, used in situations where the \fB$\fR\fIroot_path\fR\fB/etc/vfstab\fR
238 file is non-existent or unreliable.
242 .ne 2
244 \fB\fB-x\fR \fIproxy\fR\fR
246 .sp .6
247 .RS 4n
248 Specify a HTTP[S] proxy to use when downloading packages The format of proxy is
249 \fIhost\fR:\fIport\fR, where \fIhost\fR is the hostname of the HTTP[S] proxy,
250 and \fIport\fR is the port number associated with the proxy. This switch
251 overrides all other methods of specifying a proxy. See ENVIRONMENT VARIABLES
252 for more information on alternate methods of specifying a default proxy.
257 When executed without options or operands, \fBpkgadd\fR uses
258 \fB/var/spool/pkg\fR (the default spool directory).
259 .SH OPERANDS
262 The following operands are supported:
263 .SS "Sources"
266 By default, pkgadd looks in the \fB/var/spool/pkg\fR directory when searching
267 for instances of a package to install or spool. Optionally, the source for the
268 package instances to be installed or spooled can be specified using:
270 .ne 2
272 \fB\fB-d\fR \fIdevice\fR\fR
276 \fB\fB-d\fR \fIdatastream\fR \fIpkgname\fR,... | \fBall\fR\fR
278 .sp .6
279 .RS 4n
280 Install or copy a package from \fIdevice\fR. \fIdevice\fR can be any of the
281 following:
282 .RS +4
284 .ie t \(bu
285 .el o
286 A full path name to a directory or the identifiers for tape, floppy disk, or
287 removable disk (for example, \fB/var/tmp\fR or
288 \fB/floppy/\fIfloppy_name\fR\fR).
290 .RS +4
292 .ie t \(bu
293 .el o
294 A device alias (for example, \fB/floppy/floppy0\fR).
296 .RS +4
298 .ie t \(bu
299 .el o
300 A datastream created by \fBpkgtrans\fR (see \fBpkgtrans\fR(1)).
302 .RS +4
304 .ie t \(bu
305 .el o
306 A URL pointing to a datastream created by \fBpkgtrans\fR. The supported
307 Universal Resource Identifiers (URIs) are \fBhttp:\fR and \fBhttps:\fR.
309 The second form of the \fB-d\fR specifier, above, indicates the syntax you use
310 when specifying a datastream. In this case you must specify either a
311 comma-separated list of package names or the keyword \fBall\fR.
314 .SS "Instances"
317 By default, \fBpkgadd\fR searches the specified source, and presents an
318 interactive menu allowing the user to select which package instances found on
319 the source are to be installed. As an alternative, the package instances to be
320 installed can be specified using:
322 .ne 2
324 \fB\fIpkginst\fR\fR
326 .sp .6
327 .RS 4n
328 The package instance or list of instances to be installed. The token \fBall\fR
329 may be used to refer to all packages available on the source medium. The format
330 \fIpkginst\fR\fB\&.*\fR can be used to indicate all instances of a package.
332 The asterisk character (\fB*\fR) is a special character to some shells and may
333 need to be escaped. In the C-Shell, the asterisk must be surrounded by single
334 quotes (\fB\&'\fR) or preceded by a backslash (\fB\e\fR).
338 .ne 2
340 \fB\fB-Y\fR \fIcategory\fR[,\fIcategory\fR...]\fR
342 .sp .6
343 .RS 4n
344 Install packages based on the value of the \fBCATEGORY\fR parameter stored in
345 the package's \fBpkginfo\fR(4) file. All packages on the source medium whose
346 \fBCATEGORY\fR matches one of the specified categories will be selected for
347 installation or spooling.
350 .SH KEYSTORE LOCATIONS
353 Package and tools such as \fBpkgadd\fR use a set of trusted certificates to
354 perform signature validation on any signatures found within the packages. If
355 there are no signatures included in the packages then signature validation is
356 skipped. The certificates can come from a variety of locations. If \fB-k\fR
357 \fIkeystore\fR is specified, and \fIkeystore\fR is a directory, then
358 \fIkeystore\fR is assumed to be the base directory of the certificates to be
359 used. If \fIkeystore\fR is a file, then the file itself is assumed to have all
360 required keys and certificates. When \fB-k\fR is not specified, then
361 \fB/var/sadm/security\fR is used as the base directory.
364 Within the specified base directory, the store locations to be searched are
365 different based on the application doing the searching and the type of store
366 being searched for. The following directories are searched in the specified
367 order:
368 .RS +4
371 \fI<store_dir>\fR/\fI<app_name>\fR/\fI<store_type>\fR
373 .RS +4
376 \fI<store_dir>\fR/\fI<store_type>\fR
380 Where \fI<store_dir>\fR is the directory specified by \fB-k\fR,
381 \fI<app_name>\fR is the name of the application doing the searching, and
382 \fI<store_type>\fR is one of \fBkeystore\fR (for private keys), \fBcertstore\fR
383 (for untrusted public key certificates), or \fBtruststore\fR (for trusted
384 certificate authority certificates).
387 For example, when \fBpkgadd\fR is run with \fB-k\fR \fB/export/certs\fR, then
388 the following locations are successively searched to find the trust store:
389 .RS +4
392 /export/certs/pkgadd/truststore
394 .RS +4
397 /export/certs/truststore
401 This searching order enables administrators to have a single location for most
402 applications, and special certificate locations for certain applications.
403 .SH KEYSTORE AND CERTIFICATE FORMATS
406 The packaging utilities, such as \fBpkgtrans\fR, require access to a set of
407 keys and certificates in order to sign, and optionally verify, packages.
410 The keystore files found by following the search pattern specified in
411 \fBKEYSTORE LOCATIONS\fR must each be a self-contained PKCS#12-format file.
414 When signing a package with \fBpkgtrans\fR, if a \fBcertstore\fR has more than
415 one public key certificate, then each public key must have a \fBfriendlyName\fR
416 attribute in order to be identifiable and selectable with the \fB-a\fR option
417 when signing packages. In addition, the public key certificate selected with
418 \fB-a\fR and found in the \fBcertstore\fR must have an associated private key
419 in the keystore.
422 Several browsers and utilities can be used to export and import certificates
423 and keys into a PKCS#12 keystore. For example, a trusted certificate can be
424 exported from Mozilla, and then imported into a PKCS#12 keystore for use with
425 \fBpkgadd\fR with the OpenSSL Toolkit.
426 .SH PASS PHRASE ARGUMENTS
429 \fBpkgtrans\fR and \fBpkgadd\fR accept password arguments, typically using
430 \fB-p\fR to specify the password. These allow the password to be obtained from
431 a variety of sources. Both of these options take a single argument whose format
432 is described below. If no password argument is given and a password is required
433 then the user is prompted to enter one: this will typically be read from the
434 current terminal with echoing turned off.
436 .ne 2
438 \fB\fBpass:\fIpassword\fR\fR\fR
440 .sp .6
441 .RS 4n
442 The actual password is \fIpassword\fR. Because the password is visible to
443 utilities such as \fBps\fR this form should only be used where security is not
444 important.
448 .ne 2
450 \fB\fBenv:\fIvar\fR\fR\fR
452 .sp .6
453 .RS 4n
454 Obtain the password from the environment variable \fIvar\fR. Because the
455 environment of other processes is visible on certain platforms this option
456 should be used with caution.
460 .ne 2
462 \fB\fBfile:\fIpathname\fR\fR\fR
464 .sp .6
465 .RS 4n
466 The first line contained within \fIpathname\fR is the password. \fIpathname\fR
467 need not refer to a regular file: it could, for example, refer to a device or
468 named pipe. For example, to read the password from standard input, use
469 \fBfile:/dev/stdin\fR.
473 .ne 2
475 \fB\fBconsole\fR\fR
477 .sp .6
478 .RS 4n
479 Read the password from \fB/dev/tty\fR.
482 .SH EXAMPLES
484 \fBExample 1 \fRInstalling a Package from a Solaris DVD
487 The following example installs a package from a Solaris DVD. You are prompted
488 for the name of the package you want to install.
491 .in +2
493 example# \fBpkgadd -d /cdrom/cdrom0/s0/Solaris_10/Product\fR
495 .in -2
499 \fBExample 2 \fRInstalling a Set of Packages from a Datastream
502 The example command shown below installs all of the packages in the datastream
503 specified by the \fB-d\fR source specifier. Prior to this command, this
504 datastream must have been created with the \fBpkgtrans\fR(1) command.
507 .in +2
509 example# \fBpkgadd -d /var/tmp/datastream all\fR
511 .in -2
516 The keyword \fBall\fR specifies that all of the packages found in the
517 designated datastream will be installed.
519 .SH EXIT STATUS
521 .ne 2
523 \fB\fB0\fR\fR
525 .sp .6
526 .RS 4n
527 Successful completion
531 .ne 2
533 \fB\fB1\fR\fR
535 .sp .6
536 .RS 4n
537 Fatal error.
541 .ne 2
543 \fB\fB2\fR\fR
545 .sp .6
546 .RS 4n
547 Warning.
551 .ne 2
553 \fB\fB3\fR\fR
555 .sp .6
556 .RS 4n
557 Interruption.
561 .ne 2
563 \fB\fB4\fR\fR
565 .sp .6
566 .RS 4n
567 Administration.
571 .ne 2
573 \fB\fB5\fR\fR
575 .sp .6
576 .RS 4n
577 Administration. Interaction is required. Do not use \fBpkgadd\fR \fB-n\fR.
581 .ne 2
583 \fB\fB10\fR\fR
585 .sp .6
586 .RS 4n
587 Reboot after installation of all packages.
591 .ne 2
593 \fB\fB20\fR\fR
595 .sp .6
596 .RS 4n
597 Reboot after installation of this package.
600 .SH ENVIRONMENT VARIABLES
602 .ne 2
604 \fB\fBHTTPPROXY\fR\fR
606 .sp .6
607 .RS 4n
608 Specifies an HTTP proxy host. Overrides administration file setting, and
609 \fBhttp_proxy\fR environment variable.
613 .ne 2
615 \fB\fBHTTPPROXYPORT\fR\fR
617 .sp .6
618 .RS 4n
619 Specifies the port to use when contacting the host specified by
620 \fBHTTPPROXY\fR. Ignored if \fBHTTPPROXY\fR is not set.
624 .ne 2
626 \fB\fBhttp_proxy\fR\fR
628 .sp .6
629 .RS 4n
630 URL format for specifying proxy host and port. Overrides administration file
631 setting.
634 .SH FILES
636 .ne 2
638 \fB\fB/var/sadm/install/logs/\fR\fR
640 .sp .6
641 .RS 4n
642 Location where \fBpkgadd\fR logs an instance of software installation.
645 .SH ATTRIBUTES
648 See \fBattributes\fR(5) for descriptions of the following attributes:
653 box;
654 c | c
655 l | l .
656 ATTRIBUTE TYPE  ATTRIBUTE VALUE
658 Interface Stability     Evolving
661 .SH SEE ALSO
664 \fBpkginfo\fR(1), \fBpkgmk\fR(1), \fBpkgparam\fR(1), \fBpkgproto\fR(1),
665 \fBpkgtrans\fR(1), \fBinstallf\fR(1M), \fBpkgadm\fR(1M), \fBpkgask\fR(1M),
666 \fBpkgchk\fR(1M), \fBpkgrm\fR(1M), \fBremovef\fR(1M), \fBadmin\fR(4),
667 \fBpkginfo\fR(4), \fBattributes\fR(5), \fBlargefile\fR(5), \fBzones\fR(5)
670 \fI\fR
673 \fBhttp://www.openssl.org\fR
674 .SH NOTES
677 When transferring a package to a spool directory, the \fB-r\fR, \fB-n\fR, and
678 \fB-a\fR options cannot be used.
681 The \fB-r\fR option can be used to indicate a directory name as well as a
682 filename. The directory can contain numerous response files, each sharing the
683 name of the package with which it should be associated. This would be used, for
684 example, when adding multiple interactive packages with one invocation of
685 \fBpkgadd\fR. In this situation, each package would need a response file. If
686 you create response files with the same name as the package (for example,
687 \fBpkinst1\fR and \fBpkinst2\fR), then name the directory in which these files
688 reside after the \fB-r\fR.
691 The \fB-n\fR option causes the installation to halt if any interaction is
692 needed to complete it.
695 If the default \fIadmin\fR file is too restrictive, the administration file may
696 need to be modified to allow for total non-interaction during a package
697 installation. See \fBadmin\fR(4) for details.
700 If a package stream is specified with \fB-d\fR, and a digital signature is
701 found in that stream, the default behavior is to attempt to validate the
702 certificate and signature found. This behavior can be overridden with
703 \fBadmin\fR file settings. See \fBadmin\fR(4) for more information.