1 '\" te
2 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
3 .\" Copyright 2015 Nexenta Systems, Inc. All Rights Reserved.
4 .\" Copyright (c) 2013 by Delphix. All rights reserved.
5 .\" 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.
6 .\" 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.
7 .\" 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]
8 .TH DUMPADM 1M "Apr 09, 2015"
9 .SH NAME
10 dumpadm \- configure operating system crash dump
11 .SH SYNOPSIS
12 .LP
13 .nf
14 \fB/usr/sbin/dumpadm\fR [\fB-enuy\fR] [\fB-c\fR \fIcontent-type\fR] [\fB-d\fR \fIdump-device\fR]
15 [\fB-m\fR \fImin\fRk | \fImin\fRm | \fImin\fR%] [\fB-s\fR \fIsavecore-dir\fR]
16 [\fB-r\fR \fIroot-dir\fR] [\fB-z\fR on | off]
17 .fi
18
19 .SH DESCRIPTION
20 .sp
21 .LP
22 The \fBdumpadm\fR program is an administrative command that manages the
23 configuration of the operating system crash dump facility. A crash dump is a
24 disk copy of the physical memory of the computer at the time of a fatal system
25 error. When a fatal operating system error occurs, a message describing the
26 error is printed to the console. The operating system then generates a crash
27 dump by writing the contents of physical memory to a predetermined dump device,
28 which is typically a local disk partition. The dump device can be configured by
29 way of \fBdumpadm\fR. Once the crash dump has been written to the dump device,
30 the system will reboot.
31 .sp
32 .LP
33 Fatal operating system errors can be caused by bugs in the operating system,
34 its associated device drivers and loadable modules, or by faulty hardware.
35 Whatever the cause, the crash dump itself provides invaluable information to
36 your support engineer to aid in diagnosing the problem. As such, it is vital
37 that the crash dump be retrieved and given to your support provider. Following
38 an operating system crash, the \fBsavecore\fR(1M) utility is executed
39 automatically during boot to retrieve the crash dump from the dump device, and
40 write it to the file system. The directory in which the crash
48 writes two files named \fIunix.X\fR and \fIvmcore.X\fR. In the uncompressed
49 case, both data files form the \fIsaved crash dump\fR. In both cases X is an
50 integer identifying the dump.
51 .sp
52 .LP
53 For systems with a UFS root file system, the default dump device is configured
54 to be an appropriate swap partition. Swap partitions are disk partitions
55 reserved as virtual memory backing store for the operating system. Thus, no
56 permanent information resides in swap to be overwritten by the dump. See
57 \fBswap\fR(1M). For systems with a ZFS root file system, dedicated ZFS volumes
58 are used for swap and dump areas. For further information about setting up a
59 dump area with ZFS, see the \fIZFS Administration Guide\fR. To view the
60 current dump configuration, use the \fBdumpadm\fR command with no arguments:
61 .sp
62 .in +2
63 .nf
64 example# \fBdumpadm\fR
65
66 Dump content: kernel pages
67 Dump device: /dev/dsk/c0t0d0s1 (swap)
68 Savecore directory: /var/crash/saturn
69 Savecore enabled: yes
70 Save compressed: on
71 .fi
72 .in -2
73 .sp
74
75 .sp
76 .LP
77 When no options are specified, \fBdumpadm\fR prints the current crash dump
78 configuration. The example shows the set of default values: the dump content is
79 set to kernel memory pages only, the dump device is a swap disk partition, the
80 directory for \fBsavecore\fR files is set to
81 \fB/var/crash/\fR\fIhostname\fR\fB,\fR \fBsavecore\fR is set to run
82 automatically on reboot, and compression is turned on.
83 .sp
84 .LP
85 When one or more options are specified, \fBdumpadm\fR verifies that your
86 changes are valid, and if so, reconfigures the crash dump parameters and
87 displays the resulting configuration. You must be \fBroot\fR to view or change
88 dump parameters.
89 .SH OPTIONS
90 .sp
91 .LP
92 The following options are supported:
93 .sp
94 .ne 2
95 .na
96 \fB\fB-c\fR \fIcontent-type\fR\fR
97 .ad
98 .sp .6
99 .RS 4n
100 Modify the dump configuration so that the crash dump consists of the specified
101 dump content. The content should be one of the following:
102 .sp
103 .ne 2
104 .na
105 \fB\fBkernel\fR\fR
106 .ad
107 .sp .6
108 .RS 4n
109 Kernel memory pages only.
110 .RE
269 .ad
270 .sp .6
271 .RS 4n
272 Specify an alternate root directory relative to which \fBdumpadm\fR should
273 create files. If no \fB-r\fR argument is specified, the default root directory
274 \fB/\fR is used.
275 .RE
276
277 .sp
278 .ne 2
279 .na
280 \fB\fB-s\fR \fIsavecore-dir\fR\fR
281 .ad
282 .sp .6
283 .RS 4n
284 Modify the dump configuration to use the specified directory to save files
285 written by \fBsavecore\fR. The directory should be an absolute path and exist
286 on the system. If upon reboot the directory does not exist, it will be created
287 prior to the execution of \fBsavecore\fR. See the \fBNOTES\fR section below for
288 a discussion of security issues relating to access to the savecore directory.
289 The default savecore directory is \fB/var/crash/\fIhostname\fR\fR where
290 \fIhostname\fR is the output of the \fB-n\fR option to the \fBuname\fR(1)
291 command.
292 .RE
293
294 .sp
295 .ne 2
296 .na
297 \fB\fB-u\fR\fR
298 .ad
299 .sp .6
300 .RS 4n
301 Forcibly update the kernel dump configuration based on the contents of
302 \fB/etc/dumpadm.conf\fR. Normally this option is used only on reboot when
303 starting \fBsvc:/system/dumpadm:default\fR, when the \fBdumpadm\fR settings
304 from the previous boot must be restored. Your dump configuration is saved in
305 the configuration file for this purpose. If the configuration file is missing
306 or contains invalid values for any dump properties, the default values are
307 substituted. Following the update, the configuration file is resynchronized
308 with the kernel dump configuration.
309 .RE
310
311 .sp
326 .ad
327 .sp .6
328 .RS 4n
329 Turns crash dump compression \fBon\fR or \fBoff\fR.
330 .RE
331
332 .SH EXAMPLES
333 .LP
334 \fBExample 1 \fRReconfiguring The Dump Device To A Dedicated Dump Device:
335 .sp
336 .LP
337 The following command reconfigures the dump device to a dedicated dump device:
338
339 .sp
340 .in +2
341 .nf
342 example# dumpadm -d /dev/dsk/c0t2d0s2
343
344 Dump content: kernel pages
345 Dump device: /dev/dsk/c0t2d0s2 (dedicated)
346 Savecore directory: /var/crash/saturn
347 Savecore enabled: yes
348 Save compressed: on
349 .fi
350 .in -2
351 .sp
352
353 .SH EXIT STATUS
354 .sp
355 .LP
356 The following exit values are returned:
357 .sp
358 .ne 2
359 .na
360 \fB\fB0\fR\fR
361 .ad
362 .sp .6
363 .RS 4n
364 Dump configuration is valid and the specified modifications, if any, were made
365 successfully.
366 .RE
367
368 .sp
369 .ne 2
370 .na
371 \fB\fB1\fR\fR
372 .ad
373 .sp .6
374 .RS 4n
375 A fatal error occurred in either obtaining or modifying the dump configuration.
376 .RE
377
378 .sp
379 .ne 2
380 .na
381 \fB\fB2\fR\fR
382 .ad
383 .sp .6
384 .RS 4n
385 Invalid command line options were specified.
386 .RE
387
388 .SH FILES
389 .sp
390 .ne 2
391 .na
392 \fB\fB/dev/dump\fR\fR
393 .ad
394 .sp .6
395 .RS 4n
396 Dump device.
397 .RE
398
399 .sp
400 .ne 2
401 .na
402 \fB\fB/etc/dumpadm.conf\fR\fR
403 .ad
404 .sp .6
405 .RS 4n
406 Contains configuration parameters for \fBdumpadm\fR. Modifiable only through
407 that command.
408 .RE
409
410 .sp
411 .ne 2
412 .na
413 \fB\fIsavecore-directory\fR\fB/minfree\fR\fR
414 .ad
415 .sp .6
416 .RS 4n
417 Contains minimum amount of free space for \fIsavecore-directory\fR. See
418 \fBsavecore\fR(1M).
419 .RE
420
421 .SH SEE ALSO
422 .sp
423 .LP
424 \fBsvcs\fR(1), \fBuname\fR(1), \fBsavecore\fR(1M), \fBsvcadm\fR(1M),
425 \fBswap\fR(1M), \fBattributes\fR(5), \fBsmf\fR(5)
426 .SH NOTES
427 .sp
428 .LP
429 The system crash dump service is managed by the service management facility,
430 \fBsmf\fR(5), under the service identifier:
431 .sp
432 .in +2
433 .nf
434 svc:/system/dumpadm:default
435 .fi
436 .in -2
437 .sp
438
439 .sp
440 .LP
441 Administrative actions on this service, such as enabling, disabling, or
442 requesting restart, can be performed using \fBsvcadm\fR(1M). The service's
443 status can be queried using the \fBsvcs\fR(1) command.
444 .SS "Dump Device Selection"
445 .sp
446 .LP
447 When the special \fBswap\fR token is specified as the argument to \fBdumpadm\fR
448 \fB-d\fR the utility will attempt to configure the most appropriate swap device
449 as the dump device. \fBdumpadm\fR configures the largest swap block device as
450 the dump device; if no block devices are available for swap, the largest swap
451 entry is configured as the dump device. If no swap entries are present, or none
452 can be configured as the dump device, a warning message will be displayed.
453 While local and remote swap files can be configured as the dump device, this is
454 not recommended.
455 .SS "Dump Device/Swap Device Interaction (UFS File Systems Only)"
456 .sp
457 .LP
458 In the event that the dump device is also a swap device, and the swap device is
459 deleted by the administrator using the \fBswap\fR \fB-d\fR command, the
460 \fBswap\fR command will automatically invoke \fBdumpadm\fR \fB-d\fR \fBswap\fR
461 in order to attempt to configure another appropriate swap device as the dump
462 device. If no swap devices remain or none can be configured as the dump device,
463 the crash dump will be disabled and a warning message will be displayed.
464 Similarly, if the crash dump is disabled and the administrator adds a new swap
465 device using the \fBswap\fR \fB-a\fR command, \fBdumpadm\fR \fB-d\fR \fBswap\fR
466 will be invoked to re-enable the crash dump using the new swap device.
467 .sp
468 .LP
469 Once \fBdumpadm\fR \fB-d\fR \fBswap\fR has been issued, the new dump device is
470 stored in the configuration file for subsequent reboots. If a larger or more
471 appropriate swap device is added by the administrator, the dump device is not
472 changed; the administrator must re-execute \fBdumpadm\fR \fB-d\fR \fBswap\fR to
473 reselect the most appropriate device fom the new list of swap devices.
474 .SS "Minimum Free Space"
475 .sp
476 .LP
477 If the \fBdumpadm\fR \fB-m\fR option is used to create a \fBminfree\fR file
478 based on a percentage of the total size of the file system containing the
479 savecore directory, this value is not automatically recomputed if the file
480 system subsequently changes size. In this case, the administrator must
481 re-execute \fBdumpadm\fR \fB-m\fR to recompute the \fBminfree\fR value. If no
482 such file exists in the savecore directory, \fBsavecore\fR will default to a
483 free space threshold of one megabyte. If no free space threshold is desired, a
484 minfree file containing size 0 can be created.
485 .SS "Security Issues"
486 .sp
487 .LP
488 If, upon reboot, the specified savecore directory is not present, it will be
489 created prior to the execution of \fBsavecore\fR with permissions 0700 (read,
490 write, execute by owner only) and owner \fBroot\fR. It is recommended that
491 alternate savecore directories also be created with similar permissions, as the
492 operating system crash dump files themselves may contain secure information.
|
1 '\" te
2 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
3 .\" Copyright 2017 Nexenta Systems, Inc. All Rights Reserved.
4 .\" Copyright (c) 2013 by Delphix. All rights reserved.
5 .\" 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.
6 .\" 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.
7 .\" 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]
8 .TH DUMPADM 1M "Feb 13, 2017"
9 .SH NAME
10 dumpadm \- configure operating system crash dump
11 .SH SYNOPSIS
12 .LP
13 .nf
14 \fB/usr/sbin/dumpadm\fR [\fB-enuy\fR] [\fB-c\fR \fIcontent-type\fR] [\fB-d\fR \fIdump-device\fR]
15 [\fB-m\fR \fImin\fRk | \fImin\fRm | \fImin\fR%] [\fB-s\fR \fIsavecore-dir\fR]
16 [\fB-r\fR \fIroot-dir\fR] [\fB-z\fR on | off]
17 .fi
18
19 .SH DESCRIPTION
20 .LP
21 The \fBdumpadm\fR program is an administrative command that manages the
22 configuration of the operating system crash dump facility. A crash dump is a
23 disk copy of the physical memory of the computer at the time of a fatal system
24 error. When a fatal operating system error occurs, a message describing the
25 error is printed to the console. The operating system then generates a crash
26 dump by writing the contents of physical memory to a predetermined dump device,
27 which is typically a local disk partition. The dump device can be configured by
28 way of \fBdumpadm\fR. Once the crash dump has been written to the dump device,
29 the system will reboot.
30 .sp
31 .LP
32 Fatal operating system errors can be caused by bugs in the operating system,
33 its associated device drivers and loadable modules, or by faulty hardware.
34 Whatever the cause, the crash dump itself provides invaluable information to
35 your support engineer to aid in diagnosing the problem. As such, it is vital
36 that the crash dump be retrieved and given to your support provider. Following
37 an operating system crash, the \fBsavecore\fR(1M) utility is executed
38 automatically during boot to retrieve the crash dump from the dump device, and
39 write it to the file system. The directory in which the crash
47 writes two files named \fIunix.X\fR and \fIvmcore.X\fR. In the uncompressed
48 case, both data files form the \fIsaved crash dump\fR. In both cases X is an
49 integer identifying the dump.
50 .sp
51 .LP
52 For systems with a UFS root file system, the default dump device is configured
53 to be an appropriate swap partition. Swap partitions are disk partitions
54 reserved as virtual memory backing store for the operating system. Thus, no
55 permanent information resides in swap to be overwritten by the dump. See
56 \fBswap\fR(1M). For systems with a ZFS root file system, dedicated ZFS volumes
57 are used for swap and dump areas. For further information about setting up a
58 dump area with ZFS, see the \fIZFS Administration Guide\fR. To view the
59 current dump configuration, use the \fBdumpadm\fR command with no arguments:
60 .sp
61 .in +2
62 .nf
63 example# \fBdumpadm\fR
64
65 Dump content: kernel pages
66 Dump device: /dev/dsk/c0t0d0s1 (swap)
67 Savecore directory: /var/crash
68 Savecore enabled: yes
69 Save compressed: on
70 .fi
71 .in -2
72 .sp
73
74 .sp
75 .LP
76 When no options are specified, \fBdumpadm\fR prints the current crash dump
77 configuration. The example shows the set of default values: the dump content is
78 set to kernel memory pages only, the dump device is a swap disk partition, the
79 directory for \fBsavecore\fR files is set to
80 \fB/var/crash\fR, \fBsavecore\fR is set to run
81 automatically on reboot, and compression is turned on.
82 .sp
83 .LP
84 When one or more options are specified, \fBdumpadm\fR verifies that your
85 changes are valid, and if so, reconfigures the crash dump parameters and
86 displays the resulting configuration. You must be \fBroot\fR to view or change
87 dump parameters.
88 .SH OPTIONS
89 .LP
90 The following options are supported:
91 .sp
92 .ne 2
93 .na
94 \fB\fB-c\fR \fIcontent-type\fR\fR
95 .ad
96 .sp .6
97 .RS 4n
98 Modify the dump configuration so that the crash dump consists of the specified
99 dump content. The content should be one of the following:
100 .sp
101 .ne 2
102 .na
103 \fB\fBkernel\fR\fR
104 .ad
105 .sp .6
106 .RS 4n
107 Kernel memory pages only.
108 .RE
267 .ad
268 .sp .6
269 .RS 4n
270 Specify an alternate root directory relative to which \fBdumpadm\fR should
271 create files. If no \fB-r\fR argument is specified, the default root directory
272 \fB/\fR is used.
273 .RE
274
275 .sp
276 .ne 2
277 .na
278 \fB\fB-s\fR \fIsavecore-dir\fR\fR
279 .ad
280 .sp .6
281 .RS 4n
282 Modify the dump configuration to use the specified directory to save files
283 written by \fBsavecore\fR. The directory should be an absolute path and exist
284 on the system. If upon reboot the directory does not exist, it will be created
285 prior to the execution of \fBsavecore\fR. See the \fBNOTES\fR section below for
286 a discussion of security issues relating to access to the savecore directory.
287 The default savecore directory is \fB/var/crash\fR.
288 .RE
289
290 .sp
291 .ne 2
292 .na
293 \fB\fB-u\fR\fR
294 .ad
295 .sp .6
296 .RS 4n
297 Forcibly update the kernel dump configuration based on the contents of
298 \fB/etc/dumpadm.conf\fR. Normally this option is used only on reboot when
299 starting \fBsvc:/system/dumpadm:default\fR, when the \fBdumpadm\fR settings
300 from the previous boot must be restored. Your dump configuration is saved in
301 the configuration file for this purpose. If the configuration file is missing
302 or contains invalid values for any dump properties, the default values are
303 substituted. Following the update, the configuration file is resynchronized
304 with the kernel dump configuration.
305 .RE
306
307 .sp
322 .ad
323 .sp .6
324 .RS 4n
325 Turns crash dump compression \fBon\fR or \fBoff\fR.
326 .RE
327
328 .SH EXAMPLES
329 .LP
330 \fBExample 1 \fRReconfiguring The Dump Device To A Dedicated Dump Device:
331 .sp
332 .LP
333 The following command reconfigures the dump device to a dedicated dump device:
334
335 .sp
336 .in +2
337 .nf
338 example# dumpadm -d /dev/dsk/c0t2d0s2
339
340 Dump content: kernel pages
341 Dump device: /dev/dsk/c0t2d0s2 (dedicated)
342 Savecore directory: /var/crash
343 Savecore enabled: yes
344 Save compressed: on
345 .fi
346 .in -2
347 .sp
348
349 .SH EXIT STATUS
350 .LP
351 The following exit values are returned:
352 .sp
353 .ne 2
354 .na
355 \fB\fB0\fR\fR
356 .ad
357 .sp .6
358 .RS 4n
359 Dump configuration is valid and the specified modifications, if any, were made
360 successfully.
361 .RE
362
363 .sp
364 .ne 2
365 .na
366 \fB\fB1\fR\fR
367 .ad
368 .sp .6
369 .RS 4n
370 A fatal error occurred in either obtaining or modifying the dump configuration.
371 .RE
372
373 .sp
374 .ne 2
375 .na
376 \fB\fB2\fR\fR
377 .ad
378 .sp .6
379 .RS 4n
380 Invalid command line options were specified.
381 .RE
382
383 .SH FILES
384 .ne 2
385 .na
386 \fB\fB/dev/dump\fR\fR
387 .ad
388 .sp .6
389 .RS 4n
390 Dump device.
391 .RE
392
393 .sp
394 .ne 2
395 .na
396 \fB\fB/etc/dumpadm.conf\fR\fR
397 .ad
398 .sp .6
399 .RS 4n
400 Contains configuration parameters for \fBdumpadm\fR. Modifiable only through
401 that command.
402 .RE
403
404 .sp
405 .ne 2
406 .na
407 \fB\fIsavecore-directory\fR\fB/minfree\fR\fR
408 .ad
409 .sp .6
410 .RS 4n
411 Contains minimum amount of free space for \fIsavecore-directory\fR. See
412 \fBsavecore\fR(1M).
413 .RE
414
415 .SH SEE ALSO
416 .LP
417 \fBsvcs\fR(1), \fBuname\fR(1), \fBsavecore\fR(1M), \fBsvcadm\fR(1M),
418 \fBswap\fR(1M), \fBattributes\fR(5), \fBsmf\fR(5)
419 .SH NOTES
420 .LP
421 The system crash dump service is managed by the service management facility,
422 \fBsmf\fR(5), under the service identifier:
423 .sp
424 .in +2
425 .nf
426 svc:/system/dumpadm:default
427 .fi
428 .in -2
429 .sp
430
431 .sp
432 .LP
433 Administrative actions on this service, such as enabling, disabling, or
434 requesting restart, can be performed using \fBsvcadm\fR(1M). The service's
435 status can be queried using the \fBsvcs\fR(1) command.
436 .SS "Dump Device Selection"
437 .LP
438 When the special \fBswap\fR token is specified as the argument to \fBdumpadm\fR
439 \fB-d\fR the utility will attempt to configure the most appropriate swap device
440 as the dump device. \fBdumpadm\fR configures the largest swap block device as
441 the dump device; if no block devices are available for swap, the largest swap
442 entry is configured as the dump device. If no swap entries are present, or none
443 can be configured as the dump device, a warning message will be displayed.
444 While local and remote swap files can be configured as the dump device, this is
445 not recommended.
446 .SS "Dump Device/Swap Device Interaction (UFS File Systems Only)"
447 .LP
448 In the event that the dump device is also a swap device, and the swap device is
449 deleted by the administrator using the \fBswap\fR \fB-d\fR command, the
450 \fBswap\fR command will automatically invoke \fBdumpadm\fR \fB-d\fR \fBswap\fR
451 in order to attempt to configure another appropriate swap device as the dump
452 device. If no swap devices remain or none can be configured as the dump device,
453 the crash dump will be disabled and a warning message will be displayed.
454 Similarly, if the crash dump is disabled and the administrator adds a new swap
455 device using the \fBswap\fR \fB-a\fR command, \fBdumpadm\fR \fB-d\fR \fBswap\fR
456 will be invoked to re-enable the crash dump using the new swap device.
457 .sp
458 .LP
459 Once \fBdumpadm\fR \fB-d\fR \fBswap\fR has been issued, the new dump device is
460 stored in the configuration file for subsequent reboots. If a larger or more
461 appropriate swap device is added by the administrator, the dump device is not
462 changed; the administrator must re-execute \fBdumpadm\fR \fB-d\fR \fBswap\fR to
463 reselect the most appropriate device fom the new list of swap devices.
464 .SS "Minimum Free Space"
465 .LP
466 If the \fBdumpadm\fR \fB-m\fR option is used to create a \fBminfree\fR file
467 based on a percentage of the total size of the file system containing the
468 savecore directory, this value is not automatically recomputed if the file
469 system subsequently changes size. In this case, the administrator must
470 re-execute \fBdumpadm\fR \fB-m\fR to recompute the \fBminfree\fR value. If no
471 such file exists in the savecore directory, \fBsavecore\fR will default to a
472 free space threshold of one megabyte. If no free space threshold is desired, a
473 minfree file containing size 0 can be created.
474 .SS "Security Issues"
475 .LP
476 If, upon reboot, the specified savecore directory is not present, it will be
477 created prior to the execution of \fBsavecore\fR with permissions 0700 (read,
478 write, execute by owner only) and owner \fBroot\fR. It is recommended that
479 alternate savecore directories also be created with similar permissions, as the
480 operating system crash dump files themselves may contain secure information.
|