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/saturn 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 73 /var/crash/hostname, savecore is set to run automatically on reboot, 74 and compression is 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 Modify the dump configuration so that the crash dump consists of 87 the specified dump content. The content should be one of the 88 following: 89 90 kernel 91 Kernel memory pages only. 92 93 94 all 95 All memory pages. 96 97 98 curproc 99 Kernel memory pages, and the memory pages of the process whose 100 thread was currently executing on the CPU on which the crash 101 dump was initiated. If the thread executing on that CPU is a 102 kernel thread not associated with any user process, only kernel 103 pages will be dumped. 104 105 106 107 -d dump-device 108 Modify the dump configuration to use the specified dump device. The 109 dump device may be one of the following: 110 111 dump-device 112 A specific dump device specified as an absolute pathname, such 113 as /dev/dsk/cNtNdNsN when the system is running a UFS root file 114 system. Or, specify a ZFS volume, such as 115 /dev/zvol/dsk/rpool/dump, when the system is running a ZFS root 116 file system. 117 118 119 swap 120 If the special token swap is specified as the dump device, 121 dumpadm examines the active swap entries and selects the most 122 appropriate entry to configure as the dump device. See 123 swap(1M). Refer to the NOTES below for details of the algorithm 124 used to select an appropriate swap entry. When the system is 125 first installed with a UFS root file system, dumpadm uses the 126 value for swap to determine the initial dump device setting. A 127 given ZFS volume cannot be configured for both the swap area 128 and the dump device. 129 130 131 none 132 If the special token none is specified, the active dump device 133 is removed and crash dumps are disabled. 134 135 136 137 -e 138 Estimates the size of the dump for the current running system. 139 140 141 -m mink | minm | min% 142 Create a minfree file in the current savecore directory indicating 143 that savecore should maintain at least the specified amount of free 144 space in the file system where the savecore directory is located. 145 The min argument can be one of the following: 146 147 k 148 A positive integer suffixed with the unit k specifying 149 kilobytes. 150 151 152 m 153 A positive integer suffixed with the unit m specifying 154 megabytes. 155 156 157 % 158 A % symbol, indicating that the minfree value should be 159 computed as the specified percentage of the total current size 160 of the file system containing the savecore directory. 161 162 The savecore command will consult the minfree file, if present, 163 prior to writing the dump files. If the size of these files would 164 decrease the amount of free disk space below the minfree threshold, 165 no dump files are written and an error message is logged. The 166 administrator should immediately clean up the savecore directory to 167 provide adequate free space, and re-execute the savecore command 168 manually. The administrator can also specify an alternate directory 169 on the savecore command-line. 170 171 172 -n 173 Modify the dump configuration to not run savecore automatically on 174 reboot. This is not the recommended system configuration; if the 175 dump device is a swap partition, the dump data will be overwritten 176 as the system begins to swap. If savecore is not executed shortly 177 after boot, crash dump retrieval may not be possible. 178 179 180 -r root-dir 181 Specify an alternate root directory relative to which dumpadm 182 should create files. If no -r argument is specified, the default 183 root directory / is used. 184 185 186 -s savecore-dir 187 Modify the dump configuration to use the specified directory to 188 save files written by savecore. The directory should be an absolute 189 path and exist on the system. If upon reboot the directory does not 190 exist, it will be created prior to the execution of savecore. See 191 the NOTES section below for a discussion of security issues 192 relating to access to the savecore directory. The default savecore 193 directory is /var/crash/hostname where hostname is the output of 194 the -n option to the uname(1) command. 195 196 197 -u 198 Forcibly update the kernel dump configuration based on the contents 199 of /etc/dumpadm.conf. Normally this option is used only on reboot 200 when starting svc:/system/dumpadm:default, when the dumpadm 201 settings from the previous boot must be restored. Your dump 202 configuration is saved in the configuration file for this purpose. 203 If the configuration file is missing or contains invalid values for 204 any dump properties, the default values are substituted. Following 205 the update, the configuration file is resynchronized with the 206 kernel dump configuration. 207 208 209 -y 210 Modify the dump configuration to automatically run savecore on 211 reboot. This is the default for this dump setting. 212 213 214 -z on | off 215 Turns crash dump compression on or off. 216 217 218 EXAMPLES 219 Example 1 Reconfiguring The Dump Device To A Dedicated Dump Device: 220 221 222 The following command reconfigures the dump device to a dedicated dump 223 device: 224 225 226 example# dumpadm -d /dev/dsk/c0t2d0s2 227 228 Dump content: kernel pages 229 Dump device: /dev/dsk/c0t2d0s2 (dedicated) 230 Savecore directory: /var/crash/saturn 231 Savecore enabled: yes 232 Save compressed: on 233 234 235 236 EXIT STATUS 237 The following exit values are returned: 238 239 0 240 Dump configuration is valid and the specified modifications, if 241 any, were made successfully. 242 243 244 1 245 A fatal error occurred in either obtaining or modifying the dump 246 configuration. 247 248 249 2 250 Invalid command line options were specified. 251 252 253 FILES 254 /dev/dump 255 Dump device. 256 257 258 /etc/dumpadm.conf 259 Contains configuration parameters for dumpadm. Modifiable only 260 through that command. 261 262 263 savecore-directory/minfree 264 Contains minimum amount of free space for savecore-directory. See 265 savecore(1M). 266 267 268 SEE ALSO 269 svcs(1), uname(1), savecore(1M), svcadm(1M), swap(1M), attributes(5), 270 smf(5) 271 272 NOTES 273 The system crash dump service is managed by the service management 274 facility, smf(5), under the service identifier: 275 276 svc:/system/dumpadm:default 277 278 279 280 281 Administrative actions on this service, such as enabling, disabling, or 282 requesting restart, can be performed using svcadm(1M). The service's 283 status can be queried using the svcs(1) command. 284 285 Dump Device Selection 286 When the special swap token is specified as the argument to dumpadm -d 287 the utility will attempt to configure the most appropriate swap device 288 as the dump device. dumpadm configures the largest swap block device as 289 the dump device; if no block devices are available for swap, the 290 largest swap entry is configured as the dump device. If no swap entries 291 are present, or none can be configured as the dump device, a warning 292 message will be displayed. While local and remote swap files can be 293 configured as the dump device, this is not recommended. 294 295 Dump Device/Swap Device Interaction (UFS File Systems Only) 296 In the event that the dump device is also a swap device, and the swap 297 device is deleted by the administrator using the swap -d command, the 298 swap command will automatically invoke dumpadm -d swap in order to 299 attempt to configure another appropriate swap device as the dump 300 device. If no swap devices remain or none can be configured as the dump 301 device, the crash dump will be disabled and a warning message will be 302 displayed. Similarly, if the crash dump is disabled and the 303 administrator adds a new swap device using the swap -a command, dumpadm 304 -d swap will be invoked to re-enable the crash dump using the new swap 305 device. 306 307 308 Once dumpadm -d swap has been issued, the new dump device is stored in 309 the configuration file for subsequent reboots. If a larger or more 310 appropriate swap device is added by the administrator, the dump device 311 is not changed; the administrator must re-execute dumpadm -d swap to 312 reselect the most appropriate device fom the new list of swap devices. 313 314 Minimum Free Space 315 If the dumpadm -m option is used to create a minfree file based on a 316 percentage of the total size of the file system containing the savecore 317 directory, this value is not automatically recomputed if the file 318 system subsequently changes size. In this case, the administrator must 319 re-execute dumpadm -m to recompute the minfree value. If no such file 320 exists in the savecore directory, savecore will default to a free space 321 threshold of one megabyte. If no free space threshold is desired, a 322 minfree file containing size 0 can be created. 323 324 Security Issues 325 If, upon reboot, the specified savecore directory is not present, it 326 will be created prior to the execution of savecore with permissions 327 0700 (read, write, execute by owner only) and owner root. It is 328 recommended that alternate savecore directories also be created with 329 similar permissions, as the operating system crash dump files 330 themselves may contain secure information. 331 332 333 334 April 9, 2015 DUMPADM(1M)