| blob | 9f7a3d020d4d5db66a9ee9f42a35a6f8b215b319 |
1 '\" te
2 .\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved
3 .\" 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. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
4 .\" See the License for the specific language governing permissions and limitations under the License. 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
5 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH PKGADM 1M "Mar 20, 2009"
7 .SH NAME
8 pkgadm \- manage packaging and patching system
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBpkgadm addcert\fR [\fB-ty\fR] [\fB-a\fR \fIapp\fR] [\fB-k\fR \fIkeystore\fR] [\fB-e\fR \fIkeyfile\fR]
13 [\fB-f\fR \fIformat\fR] [\fB-n\fR \fIname\fR] [\fB-P\fR \fIpassarg\fR]
14 [\fB-p\fR \fIimport_passarg\fR] [\fB-R\fR \fIrootpath\fR] certfile
15 .fi
17 .LP
18 .nf
19 \fBpkgadm removecert\fR [\fB-a\fR \fIapp\fR] [\fB-k\fR \fIkeystore\fR] \fB-n\fR \fIname\fR
20 [\fB-P\fR \fIpassarg\fR] [\fB-R\fR \fIrootpath\fR]
21 .fi
23 .LP
24 .nf
25 \fBpkgadm listcert\fR [\fB-a\fR \fIapp\fR] [\fB-f\fR \fIformat\fR] [\fB-k\fR \fIkeystore\fR] \fB-n\fR \fIname\fR
26 [\fB-P\fR \fIpassarg\fR] [\fB-o\fR \fIoutfile\fR] [\fB-R\fR \fIrootpath\fR]
27 .fi
29 .LP
30 .nf
31 \fBpkgadm dbstatus\fR [\fB-R\fR \fIrootpath\fR]
32 .fi
34 .LP
35 .nf
36 \fBpkgadm sync\fR [\fB-R\fR \fIrootpath\fR] [\fB-q\fR]
37 .fi
39 .LP
40 .nf
41 \fBpkgadm\fR \fB-V\fR
42 .fi
44 .LP
45 .nf
46 \fBpkgadm\fR \fB-?\fR
47 .fi
49 .SH DESCRIPTION
50 .sp
51 .LP
52 The \fBpkgadm\fR utility is used for managing the packaging and patching
53 system. It has several subcommands that perform various operations relating to
54 packaging. The \fBpkgadm\fR command includes subcommands for managing
55 certificates and keys used.
56 .SS "Managing Keys and Certificates"
57 .sp
58 .LP
59 \fBpkgadm\fR maintains the packaging-system-wide keystore in
60 \fB/var/sadm/security\fR, and individual user's certificates in
61 \fB~/.pkg/security\fR. The following subcommands operate on the package
62 keystore database:
63 .sp
64 .ne 2
65 .na
66 \fB\fBaddcert\fR\fR
67 .ad
68 .sp .6
69 .RS 4n
70 Add (import) a certificate into the database, with optional trust. Once added,
71 trusted certificates can be used to verify signed packages and patches.
72 Non-trusted user certificates and their associated keys can be used to sign
73 packages and patches. Added user certificates are \fBnot\fR used to build
74 certificate chains during certificate verification.
75 .RE
77 .sp
78 .ne 2
79 .na
80 \fB\fBremovecert\fR\fR
81 .ad
82 .sp .6
83 .RS 4n
84 Removes a user certificate/private key pair, or a trusted certificate authority
85 certificate from the keystore. Once removed, the certificate and keys cannot be
86 used.
87 .RE
89 .sp
90 .ne 2
91 .na
92 \fB\fBlistcert\fR\fR
93 .ad
94 .sp .6
95 .RS 4n
96 Print details of one or more certificates in the keystore.
97 .RE
99 .sp
100 .ne 2
101 .na
102 \fB\fBsync\fR\fR
103 .ad
104 .sp .6
105 .RS 4n
106 Writes the contents file and rolls the contents log file. With use of the
107 \fB-q\fR option, forces the contents file server to quit.
108 .RE
110 .SS "Internal Install Database"
111 .sp
112 .LP
113 The Solaris operating system relies upon enhanced System V revision 4 (SVr4)
114 packages as the basis for its software installation and revision management.
115 The package maintenance software stores information about installed packages in
116 an internal database. The \fBpkgadm\fR subcomand \fBdbstatus\fR is used to
117 determine how the package internal database is implemented. The \fBdbstatus\fR
118 command returns a string that indicates the type of internal database in use.
119 In the current implementation, the \fBdbstatus\fR command always returns the
120 string \fBtext\fR, which indicates that the \fBcontents\fR(4) package database
121 is inuse. Future releases of Solaris might supply alternative database
122 implementations.
123 .SH OPTIONS
124 .sp
125 .LP
126 The following options are supported:
127 .sp
128 .ne 2
129 .na
130 \fB\fB-a\fR \fIapp\fR\fR
131 .ad
132 .sp .6
133 .RS 4n
134 If this option is used, then the command only affects the keystore associated
135 with a particular application. Otherwise, the global keystore is affected.
136 .RE
138 .sp
139 .ne 2
140 .na
141 \fB\fB-e\fR \fIkeyfile\fR\fR
142 .ad
143 .sp .6
144 .RS 4n
145 When adding a non-trusted certificate/key combination, this option can be used
146 to specify the file that contains the private key. If this option is not used,
147 the private key must be in the same file as the certificate being added.
148 .RE
150 .sp
151 .ne 2
152 .na
153 \fB\fB-f\fR \fIformat\fR\fR
154 .ad
155 .sp .6
156 .RS 4n
157 When adding certificates, this specifies the format to expect certificates and
158 private keys in. Possible values when adding are:
159 .sp
160 .ne 2
161 .na
162 \fB\fBpem\fR\fR
163 .ad
164 .sp .6
165 .RS 4n
166 Certificate and any private key uses PEM encoding.
167 .RE
169 .sp
170 .ne 2
171 .na
172 \fB\fBder\fR\fR
173 .ad
174 .sp .6
175 .RS 4n
176 Certificate and any private key uses DER encoding.
177 .RE
179 When printing certificates, this specifies the output format used when
180 printing. Acceptable values for format are:
181 .sp
182 .ne 2
183 .na
184 \fB\fBpem\fR\fR
185 .ad
186 .sp .6
187 .RS 4n
188 Output each certificate using PEM encoding.
189 .RE
191 .sp
192 .ne 2
193 .na
194 \fB\fBder\fR\fR
195 .ad
196 .sp .6
197 .RS 4n
198 Output each certificate using DER encoding.
199 .RE
201 .sp
202 .ne 2
203 .na
204 \fB\fBtext\fR\fR
205 .ad
206 .sp .6
207 .RS 4n
208 Output each certificate in human-readable format.
209 .RE
211 .RE
213 .sp
214 .ne 2
215 .na
216 \fB\fB-k\fR \fIkeystore\fR\fR
217 .ad
218 .sp .6
219 .RS 4n
220 Overrides the default location used when accessing the keystore.
221 .RE
223 .sp
224 .ne 2
225 .na
226 \fB\fB-n\fR \fIname\fR\fR
227 .ad
228 .sp .6
229 .RS 4n
230 Identifies the entity in the store on which you want to operate. When adding a
231 user certificate, or removing certificates, this name is required. The name is
232 associated with the certificate/key combination, and when adding, can be used
233 later to reference the entity. When printing certificates, if no alias is
234 supplied, then all keystore entities are printed.
235 .RE
237 .sp
238 .ne 2
239 .na
240 \fB\fB-o\fR \fIoutfile\fR\fR
241 .ad
242 .sp .6
243 .RS 4n
244 Output the result of the command to \fIoutfile\fR. Only used when examining
245 (printing) certificates from the key store. Standard out is the default.
246 .RE
248 .sp
249 .ne 2
250 .na
251 \fB\fB-P\fR \fIpassarg\fR\fR
252 .ad
253 .sp .6
254 .RS 4n
255 Password retrieval method to use to decrypt keystore specified with \fB-k\fR,
256 if required. See \fBPASS PHRASE ARGUMENTS\fR in \fBpkgadd\fR(1M) for more
257 information about the format of this option's argument. \fBconsole\fR is the
258 default.
259 .RE
261 .sp
262 .ne 2
263 .na
264 \fB\fB-p\fR \fIimport_passarg\fR\fR
265 .ad
266 .sp .6
267 .RS 4n
268 This option's argument is identical to \fB-P\fR, but is used for supplying the
269 password used to decrypt the certificate and/or private key being added.
270 \fBconsole\fR is the default.
271 .RE
273 .sp
274 .ne 2
275 .na
276 \fB\fB-q\fR\fR
277 .ad
278 .sp .6
279 .RS 4n
280 (Applies to \fBsync\fR subcommand.) Shuts down the contents file cache daemon.
281 .RE
283 .sp
284 .ne 2
285 .na
286 \fB\fB-R\fR \fIrootpath\fR\fR
287 .ad
288 .sp .6
289 .RS 4n
290 Defines the full name of a directory to use as the root (\fB/\fR) path. The
291 default user location of the certificate operations is \fB${HOME}/.pkg\fR. If
292 the \fB-R\fR option is supplied, the certificates and keys will be stored under
293 \fB\fI<altroot>\fR/var/sadm/security\fR. Note that this operation fails if the
294 user does not have sufficient permissions to access this directory. The
295 \fBlistcert\fR command requires read permission, while \fBaddcert\fR and
296 \fBremovecert\fR require both read and write permission.
297 .LP
298 Note -
299 .sp
300 .RS 2
301 The root file system of any non-global zones must not be referenced with the
302 \fB-R\fR option. Doing so might damage the global zone's file system, might
303 compromise the security of the global zone, and might damage the non-global
304 zone's file system. See \fBzones\fR(5).
305 .RE
306 .RE
308 .sp
309 .ne 2
310 .na
311 \fB\fB-t\fR\fR
312 .ad
313 .sp .6
314 .RS 4n
315 Indicates the certificate being added is a trusted CA certificate. The details
316 of the certificate (including the Subject Name, Validity Dates, and
317 Fingerprints) are printed and the user is asked to verify the data. This
318 verification step can be skipped with \fB-y\fR. When importing a trusted
319 certificate, a private key should not be supplied, and will be rejected if
320 supplied. Once a certificate is trusted, it can be used as a trust anchor when
321 verifying future untrusted certificates.
322 .RE
324 .sp
325 .ne 2
326 .na
327 \fB\fB-V\fR\fR
328 .ad
329 .sp .6
330 .RS 4n
331 Print version associated with packaging tools.
332 .RE
334 .sp
335 .ne 2
336 .na
337 \fB\fB-y\fR\fR
338 .ad
339 .sp .6
340 .RS 4n
341 When adding a trusted certificate, the details of the certificate (Subject
342 name, Issuer name, Validity dates, Fingerprints) are shown to the user and the
343 user is asked to verify the correctness before proceeding. With \fB-y\fR, this
344 additional verification step is skipped.
345 .RE
347 .sp
348 .ne 2
349 .na
350 \fB\fB-?\fR\fR
351 .ad
352 .sp .6
353 .RS 4n
354 Print help message.
355 .RE
357 .SH OPERANDS
358 .sp
359 .LP
360 The following operand is supported:
361 .sp
362 .ne 2
363 .na
364 \fB\fBcertfile\fR\fR
365 .ad
366 .sp .6
367 .RS 4n
368 File containing the certificate and optional private key, used when adding a
369 trust anchor or certificate/key combination. Certificates must be encoded using
370 PEM or binary DER.
371 .RE
373 .SH KEYSTORE ALIASES
374 .sp
375 .LP
376 All keystore entries (user cert/key and trusted certificate entries) are
377 accessed via unique aliases. Aliases are case-sensitive.
378 .sp
379 .LP
380 An alias is specified when you add an entity to a keystore using the
381 \fBaddcert\fR or \fBtrustcert\fR subcommand. If an alias is not supplied for a
382 trust anchor, the trust anchor's Common Name is used as the alias. An alias is
383 required when adding a signing certificate or chain certificate. Subsequent
384 \fBpkgcert\fR or other package tool commands must use this same alias to refer
385 to the entity.
386 .SH KEYSTORE PASSWORDS
387 .sp
388 .LP
389 See the \fBpkgadd\fR(1M) man page for a description of the passwords supplied
390 to the \fBpkgadm\fR utility.
391 .SH EXAMPLES
392 .LP
393 \fBExample 1 \fRAdding a Trust Anchor
394 .sp
395 .LP
396 The following example adds a well-known and trusted certificate to be used when
397 verifying signatures on packages.
399 .sp
400 .in +2
401 .nf
402 example% pkgadm addcert -t /tmp/certfile.pem
403 .fi
404 .in -2
405 .sp
407 .LP
408 \fBExample 2 \fRAdding a Signing Certificate
409 .sp
410 .LP
411 The following example adds a signing certificate and associated private key,
412 each of which is in a separate file, which can then be used to sign packages.
414 .sp
415 .in +2
416 .nf
417 example% pkgadm addcert -a pkgtrans -e /tmp/keyfile.pem \e
418 /tmp/certfile.pem
419 .fi
420 .in -2
421 .sp
423 .LP
424 \fBExample 3 \fRPrinting Certificates
425 .sp
426 .LP
427 The following example prints all certificates in the root keystore.
429 .sp
430 .in +2
431 .nf
432 example% pkgadm listcert
433 .fi
434 .in -2
435 .sp
437 .SH EXIT STATUS
438 .sp
439 .ne 2
440 .na
441 \fB\fB0\fR\fR
442 .ad
443 .sp .6
444 .RS 4n
445 successful completion
446 .RE
448 .sp
449 .ne 2
450 .na
451 \fB\fBnon-zero\fR\fR
452 .ad
453 .sp .6
454 .RS 4n
455 fatal error
456 .RE
458 .SH ATTRIBUTES
459 .sp
460 .LP
461 See \fBattributes\fR(5) for descriptions of the following attributes:
462 .sp
464 .sp
465 .TS
466 box;
467 c | c
468 l | l .
469 ATTRIBUTE TYPE ATTRIBUTE VALUE
470 _
471 Interface Stability Evolving
472 .TE
474 .SH SEE ALSO
475 .sp
476 .LP
477 \fBpkginfo\fR(1), \fBpkgmk\fR(1), \fBpkgparam\fR(1), \fBpkgproto\fR(1),
478 \fBpkgtrans\fR(1), \fBsvcs\fR(1), \fBinstallf\fR(1M), \fBpkgadd\fR(1M),
479 \fBpkgask\fR(1M), \fBpkgrm\fR(1M), \fBremovef\fR(1M), \fBsvcadm\fR(1M),
480 \fBadmin\fR(4), \fBcontents\fR(4), \fBexec_attr\fR(4), \fBpkginfo\fR(4),
481 \fBattributes\fR(5), \fBrbac\fR(5), \fBsmf\fR(5)
482 .sp
483 .LP
484 \fI\fR
485 .SH NOTES
486 .sp
487 .LP
488 The service for \fBpkgadm\fR is managed by the service management facility,
489 \fBsmf\fR(5), under the service identifier:
490 .sp
491 .in +2
492 .nf
493 svc:/system/pkgserv
494 .fi
495 .in -2
496 .sp
498 .sp
499 .LP
500 Administrative actions on this service, such as enabling, disabling, or
501 requesting restart, can be performed using \fBsvcadm\fR(1M). The service's
502 status can be queried using the \fBsvcs\fR(1) command.