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 40 dump is saved on reboot can also be configured using \fBdumpadm\fR. 41 .sp 42 .LP 43 When the operating system takes a crash dump the default behavior is to 44 compress the crash dump. This behavior is controlled by the \fB-z\fR option. 45 When compression is turned on, the \fBsavecore\fR(1M) utility writes one file 46 to the file system named \fIvmdump.X\fR. If compression is disabled, it instead 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 109 110 .sp 111 .ne 2 112 .na 113 \fB\fBall\fR\fR 114 .ad 115 .sp .6 116 .RS 4n 117 All memory pages. 118 .RE 119 120 .sp 121 .ne 2 122 .na 123 \fB\fBcurproc\fR\fR 124 .ad 125 .sp .6 126 .RS 4n 127 Kernel memory pages, and the memory pages of the process whose thread was 128 currently executing on the CPU on which the crash dump was initiated. If the 129 thread executing on that CPU is a kernel thread not associated with any user 130 process, only kernel pages will be dumped. 131 .RE 132 133 .RE 134 135 .sp 136 .ne 2 137 .na 138 \fB\fB-d\fR \fIdump-device\fR\fR 139 .ad 140 .sp .6 141 .RS 4n 142 Modify the dump configuration to use the specified dump device. The dump device 143 may be one of the following: 144 .sp 145 .ne 2 146 .na 147 \fB\fIdump-device\fR\fR 148 .ad 149 .sp .6 150 .RS 4n 151 A specific dump device specified as an absolute pathname, such as 152 \fB/dev/dsk/\fR\fIcNtNdNsN\fR when the system is running a UFS root file 153 system. Or, specify a ZFS volume, such as \fB/dev/zvol/dsk/rpool/dump\fR, when 154 the system is running a ZFS root file system. 155 .RE 156 157 .sp 158 .ne 2 159 .na 160 \fB\fBswap\fR\fR 161 .ad 162 .sp .6 163 .RS 4n 164 If the special token \fBswap\fR is specified as the dump device, \fBdumpadm\fR 165 examines the active swap entries and selects the most appropriate entry to 166 configure as the dump device. See \fBswap\fR(1M). Refer to the \fBNOTES\fR 167 below for details of the algorithm used to select an appropriate swap entry. 168 When the system is first installed with a UFS root file system, \fBdumpadm\fR 169 uses the value for \fBswap\fR to determine the initial dump device setting. A 170 given ZFS volume cannot be configured for both the swap area and the dump 171 device. 172 .RE 173 174 .sp 175 .ne 2 176 .na 177 \fB\fBnone\fR\fR 178 .ad 179 .sp .6 180 .RS 4n 181 If the special token \fBnone\fR is specified, the active dump device is removed 182 and crash dumps are disabled. 183 .RE 184 185 .RE 186 187 .sp 188 .ne 2 189 .na 190 \fB\fB-e\fR\fR 191 .ad 192 .sp .6 193 .RS 4n 194 Estimates the size of the dump for the current running system. 195 .RE 196 197 .sp 198 .ne 2 199 .na 200 \fB\fB-m\fR \fImin\fR\fBk\fR | \fImin\fR\fBm\fR | \fImin\fR\fB%\fR\fR 201 .ad 202 .sp .6 203 .RS 4n 204 Create a \fBminfree\fR file in the current savecore directory indicating that 205 \fBsavecore\fR should maintain at least the specified amount of free space in 206 the file system where the savecore directory is located. The \fBmin\fR argument 207 can be one of the following: 208 .sp 209 .ne 2 210 .na 211 \fB\fBk\fR\fR 212 .ad 213 .sp .6 214 .RS 4n 215 A positive integer suffixed with the unit \fBk\fR specifying kilobytes. 216 .RE 217 218 .sp 219 .ne 2 220 .na 221 \fB\fBm\fR\fR 222 .ad 223 .sp .6 224 .RS 4n 225 A positive integer suffixed with the unit \fBm\fR specifying megabytes. 226 .RE 227 228 .sp 229 .ne 2 230 .na 231 \fB\fB%\fR\fR 232 .ad 233 .sp .6 234 .RS 4n 235 A % symbol, indicating that the \fBminfree\fR value should be computed as the 236 specified percentage of the total current size of the file system containing 237 the savecore directory. 238 .RE 239 240 The \fBsavecore\fR command will consult the \fBminfree\fR file, if present, 241 prior to writing the dump files. If the size of these files would decrease the 242 amount of free disk space below the \fBminfree\fR threshold, no dump files are 243 written and an error message is logged. The administrator should immediately 244 clean up the savecore directory to provide adequate free space, and re-execute 245 the \fBsavecore\fR command manually. The administrator can also specify an 246 alternate directory on the \fBsavecore\fR command-line. 247 .RE 248 249 .sp 250 .ne 2 251 .na 252 \fB\fB-n\fR\fR 253 .ad 254 .sp .6 255 .RS 4n 256 Modify the dump configuration to not run \fBsavecore\fR automatically on 257 reboot. This is not the recommended system configuration; if the dump device is 258 a swap partition, the dump data will be overwritten as the system begins to 259 swap. If \fBsavecore\fR is not executed shortly after boot, crash dump 260 retrieval may not be possible. 261 .RE 262 263 .sp 264 .ne 2 265 .na 266 \fB\fB-r\fR \fIroot-dir\fR\fR 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 308 .ne 2 309 .na 310 \fB\fB-y\fR\fR 311 .ad 312 .sp .6 313 .RS 4n 314 Modify the dump configuration to automatically run \fBsavecore\fR on reboot. 315 This is the default for this dump setting. 316 .RE 317 318 .sp 319 .ne 2 320 .na 321 \fB\fB-z on | off\fR\fR 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.