1 DUMPADM(1M) Maintenance Commands DUMPADM(1M) 2 3 4 5 NAME 6 dumpadm - configure operating system crash dump 7 8 SYNOPSIS 9 /usr/sbin/dumpadm [-enuy] [-c content-type] [-d dump-device] 10 [-m mink | minm | min%] [-s savecore-dir] 11 [-r root-dir] [-z on | off] 12 13 14 DESCRIPTION 15 The dumpadm program is an administrative command that manages the 16 configuration of the operating system crash dump facility. A crash dump 17 is a disk copy of the physical memory of the computer at the time of a 18 fatal system error. When a fatal operating system error occurs, a 19 message describing the error is printed to the console. The operating 20 system then generates a crash dump by writing the contents of physical 21 memory to a predetermined dump device, which is typically a local disk 22 partition. The dump device can be configured by way of dumpadm. Once 23 the crash dump has been written to the dump device, the system will 24 reboot. 25 26 27 Fatal operating system errors can be caused by bugs in the operating 28 system, its associated device drivers and loadable modules, or by 29 faulty hardware. Whatever the cause, the crash dump itself provides 30 invaluable information to your support engineer to aid in diagnosing 31 the problem. As such, it is vital that the crash dump be retrieved and 32 given to your support provider. Following an operating system crash, 33 the savecore(1M) utility is executed automatically during boot to 34 retrieve the crash dump from the dump device, and write it to the file 35 system. The directory in which the crash dump is saved on reboot can 36 also be configured using dumpadm. 37 38 39 When the operating system takes a crash dump the default behavior is to 40 compress the crash dump. This behavior is controlled by the -z option. 41 When compression is turned on, the savecore(1M) utility writes one file 42 to the file system named vmdump.X. If compression is disabled, it 43 instead writes two files named unix.X and vmcore.X. In the uncompressed 44 case, both data files form the saved crash dump. In both cases X is an 45 integer identifying the dump. 46 47 48 For systems with a UFS root file system, the default dump device is 49 configured to be an appropriate swap partition. Swap partitions are 50 disk partitions reserved as virtual memory backing store for the 51 operating system. Thus, no permanent information resides in swap to be 52 overwritten by the dump. See swap(1M). For systems with a ZFS root file 53 system, dedicated ZFS volumes are used for swap and dump areas. For 54 further information about setting up a dump area with ZFS, see the ZFS 55 Administration Guide. To view the current dump configuration, use the 56 dumpadm command with no arguments: 57 58 example# dumpadm 59 60 Dump content: kernel pages 61 Dump device: /dev/dsk/c0t0d0s1 (swap) 62 Savecore directory: /var/crash 63 Savecore enabled: yes 64 Save compressed: on 65 66 67 68 69 When no options are specified, dumpadm prints the current crash dump 70 configuration. The example shows the set of default values: the dump 71 content is set to kernel memory pages only, the dump device is a swap 72 disk partition, the directory for savecore files is set to /var/crash, 73 savecore is set to run automatically on reboot, and compression is 74 turned on. 75 76 77 When one or more options are specified, dumpadm verifies that your 78 changes are valid, and if so, reconfigures the crash dump parameters 79 and displays the resulting configuration. You must be root to view or 80 change dump parameters. 81 82 OPTIONS 83 The following options are supported: 84 85 -c content-type 86 87 Modify the dump configuration so that the crash dump consists of 88 the specified dump content. The content should be one of the 89 following: 90 91 kernel 92 93 Kernel memory pages only. 94 95 96 all 97 98 All memory pages. 99 100 101 curproc 102 103 Kernel memory pages, and the memory pages of the process whose 104 thread was currently executing on the CPU on which the crash 105 dump was initiated. If the thread executing on that CPU is a 106 kernel thread not associated with any user process, only kernel 107 pages will be dumped. 108 109 110 111 -d dump-device 112 113 Modify the dump configuration to use the specified dump device. The 114 dump device may be one of the following: 115 116 dump-device 117 118 A specific dump device specified as an absolute pathname, such 119 as /dev/dsk/cNtNdNsN when the system is running a UFS root file 120 system. Or, specify a ZFS volume, such as 121 /dev/zvol/dsk/rpool/dump, when the system is running a ZFS root 122 file system. 123 124 125 swap 126 127 If the special token swap is specified as the dump device, 128 dumpadm examines the active swap entries and selects the most 129 appropriate entry to configure as the dump device. See 130 swap(1M). Refer to the NOTES below for details of the algorithm 131 used to select an appropriate swap entry. When the system is 132 first installed with a UFS root file system, dumpadm uses the 133 value for swap to determine the initial dump device setting. A 134 given ZFS volume cannot be configured for both the swap area 135 and the dump device. 136 137 138 none 139 140 If the special token none is specified, the active dump device 141 is removed and crash dumps are disabled. 142 143 144 145 -e 146 147 Estimates the size of the dump for the current running system. 148 149 150 -m mink | minm | min% 151 152 Create a minfree file in the current savecore directory indicating 153 that savecore should maintain at least the specified amount of free 154 space in the file system where the savecore directory is located. 155 The min argument can be one of the following: 156 157 k 158 159 A positive integer suffixed with the unit k specifying 160 kilobytes. 161 162 163 m 164 165 A positive integer suffixed with the unit m specifying 166 megabytes. 167 168 169 % 170 171 A % symbol, indicating that the minfree value should be 172 computed as the specified percentage of the total current size 173 of the file system containing the savecore directory. 174 175 The savecore command will consult the minfree file, if present, 176 prior to writing the dump files. If the size of these files would 177 decrease the amount of free disk space below the minfree threshold, 178 no dump files are written and an error message is logged. The 179 administrator should immediately clean up the savecore directory to 180 provide adequate free space, and re-execute the savecore command 181 manually. The administrator can also specify an alternate directory 182 on the savecore command-line. 183 184 185 -n 186 187 Modify the dump configuration to not run savecore automatically on 188 reboot. This is not the recommended system configuration; if the 189 dump device is a swap partition, the dump data will be overwritten 190 as the system begins to swap. If savecore is not executed shortly 191 after boot, crash dump retrieval may not be possible. 192 193 194 -r root-dir 195 196 Specify an alternate root directory relative to which dumpadm 197 should create files. If no -r argument is specified, the default 198 root directory / is used. 199 200 201 -s savecore-dir 202 203 Modify the dump configuration to use the specified directory to 204 save files written by savecore. The directory should be an absolute 205 path and exist on the system. If upon reboot the directory does not 206 exist, it will be created prior to the execution of savecore. See 207 the NOTES section below for a discussion of security issues 208 relating to access to the savecore directory. The default savecore 209 directory is /var/crash. 210 211 212 -u 213 214 Forcibly update the kernel dump configuration based on the contents 215 of /etc/dumpadm.conf. Normally this option is used only on reboot 216 when starting svc:/system/dumpadm:default, when the dumpadm 217 settings from the previous boot must be restored. Your dump 218 configuration is saved in the configuration file for this purpose. 219 If the configuration file is missing or contains invalid values for 220 any dump properties, the default values are substituted. Following 221 the update, the configuration file is resynchronized with the 222 kernel dump configuration. 223 224 225 -y 226 227 Modify the dump configuration to automatically run savecore on 228 reboot. This is the default for this dump setting. 229 230 231 -z on | off 232 233 Turns crash dump compression on or off. 234 235 236 EXAMPLES 237 Example 1 Reconfiguring The Dump Device To A Dedicated Dump Device: 238 239 240 The following command reconfigures the dump device to a dedicated dump 241 device: 242 243 244 example# dumpadm -d /dev/dsk/c0t2d0s2 245 246 Dump content: kernel pages 247 Dump device: /dev/dsk/c0t2d0s2 (dedicated) 248 Savecore directory: /var/crash 249 Savecore enabled: yes 250 Save compressed: on 251 252 253 254 EXIT STATUS 255 The following exit values are returned: 256 257 0 258 259 Dump configuration is valid and the specified modifications, if 260 any, were made successfully. 261 262 263 1 264 265 A fatal error occurred in either obtaining or modifying the dump 266 configuration. 267 268 269 2 270 271 Invalid command line options were specified. 272 273 274 FILES 275 /dev/dump 276 277 Dump device. 278 279 280 /etc/dumpadm.conf 281 282 Contains configuration parameters for dumpadm. Modifiable only 283 through that command. 284 285 286 savecore-directory/minfree 287 288 Contains minimum amount of free space for savecore-directory. See 289 savecore(1M). 290 291 292 SEE ALSO 293 svcs(1), uname(1), savecore(1M), svcadm(1M), swap(1M), attributes(5), 294 smf(5) 295 296 NOTES 297 The system crash dump service is managed by the service management 298 facility, smf(5), under the service identifier: 299 300 svc:/system/dumpadm:default 301 302 303 304 305 Administrative actions on this service, such as enabling, disabling, or 306 requesting restart, can be performed using svcadm(1M). The service's 307 status can be queried using the svcs(1) command. 308 309 Dump Device Selection 310 When the special swap token is specified as the argument to dumpadm -d 311 the utility will attempt to configure the most appropriate swap device 312 as the dump device. dumpadm configures the largest swap block device as 313 the dump device; if no block devices are available for swap, the 314 largest swap entry is configured as the dump device. If no swap entries 315 are present, or none can be configured as the dump device, a warning 316 message will be displayed. While local and remote swap files can be 317 configured as the dump device, this is not recommended. 318 319 Dump Device/Swap Device Interaction (UFS File Systems Only) 320 In the event that the dump device is also a swap device, and the swap 321 device is deleted by the administrator using the swap -d command, the 322 swap command will automatically invoke dumpadm -d swap in order to 323 attempt to configure another appropriate swap device as the dump 324 device. If no swap devices remain or none can be configured as the dump 325 device, the crash dump will be disabled and a warning message will be 326 displayed. Similarly, if the crash dump is disabled and the 327 administrator adds a new swap device using the swap -a command, dumpadm 328 -d swap will be invoked to re-enable the crash dump using the new swap 329 device. 330 331 332 Once dumpadm -d swap has been issued, the new dump device is stored in 333 the configuration file for subsequent reboots. If a larger or more 334 appropriate swap device is added by the administrator, the dump device 335 is not changed; the administrator must re-execute dumpadm -d swap to 336 reselect the most appropriate device fom the new list of swap devices. 337 338 Minimum Free Space 339 If the dumpadm -m option is used to create a minfree file based on a 340 percentage of the total size of the file system containing the savecore 341 directory, this value is not automatically recomputed if the file 342 system subsequently changes size. In this case, the administrator must 343 re-execute dumpadm -m to recompute the minfree value. If no such file 344 exists in the savecore directory, savecore will default to a free space 345 threshold of one megabyte. If no free space threshold is desired, a 346 minfree file containing size 0 can be created. 347 348 Security Issues 349 If, upon reboot, the specified savecore directory is not present, it 350 will be created prior to the execution of savecore with permissions 351 0700 (read, write, execute by owner only) and owner root. It is 352 recommended that alternate savecore directories also be created with 353 similar permissions, as the operating system crash dump files 354 themselves may contain secure information. 355 356 357 358 February 13, 2017 DUMPADM(1M)