5819 want dumpadm(1m) option to print estimated dump size

          --- old/usr/src/man/man1m/dumpadm.1m
          +++ new/usr/src/man/man1m/dumpadm.1m
   1    1  '\" te
   2    2  .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
   3      -.\" Copyright 2013 Nexenta Systems, Inc.  All Rights Reserved.
        3 +.\" Copyright 2015 Nexenta Systems, Inc.  All Rights Reserved.
   4    4  .\" Copyright (c) 2013 by Delphix. All rights reserved.
   5    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    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    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 15, 2013"
        8 +.TH DUMPADM 1M "Apr 09, 2015"
   9    9  .SH NAME
  10   10  dumpadm \- configure operating system crash dump
  11   11  .SH SYNOPSIS
  12   12  .LP
  13   13  .nf
  14      -\fB/usr/sbin/dumpadm\fR [\fB-nuy\fR] [\fB-c\fR \fIcontent-type\fR] [\fB-d\fR \fIdump-device\fR]
       14 +\fB/usr/sbin/dumpadm\fR [\fB-enuy\fR] [\fB-c\fR \fIcontent-type\fR] [\fB-d\fR \fIdump-device\fR]
  15   15       [\fB-m\fR \fImin\fRk | \fImin\fRm | \fImin\fR%] [\fB-s\fR \fIsavecore-dir\fR]
  16   16       [\fB-r\fR \fIroot-dir\fR] [\fB-z\fR on | off]
  17   17  .fi
  18   18  
  19   19  .SH DESCRIPTION
  20   20  .sp
  21   21  .LP
  22   22  The \fBdumpadm\fR program is an administrative command that manages the
  23   23  configuration of the operating system crash dump facility. A crash dump is a
  24   24  disk copy of the physical memory of the computer at the time of a fatal system

  25   25  error. When a fatal operating system error occurs, a message describing the
  26   26  error is printed to the console. The operating system then generates a crash
  27   27  dump by writing the contents of physical memory to a predetermined dump device,
  28   28  which is typically a local disk partition. The dump device can be configured by
  29   29  way of \fBdumpadm\fR. Once the crash dump has been written to the dump device,
  30   30  the system will reboot.
  31   31  .sp
  32   32  .LP
  33   33  Fatal operating system errors can be caused by bugs in the operating system,
  34   34  its associated device drivers and loadable modules, or by faulty hardware.
  35   35  Whatever the cause, the crash dump itself provides invaluable information to
  36   36  your support engineer to aid in diagnosing the problem. As such, it is vital
  37   37  that the crash dump be retrieved and given to your support provider. Following
  38   38  an operating system crash, the \fBsavecore\fR(1M) utility is executed
  39   39  automatically during boot to retrieve the crash dump from the dump device, and
  40   40  write it to the file system. The directory in which the crash
  41   41  dump is saved on reboot can also be configured using \fBdumpadm\fR.
  42   42  .sp
  43   43  .LP
  44   44  When the operating system takes a crash dump the default behavior is to
  45   45  compress the crash dump. This behavior is controlled by the \fB-z\fR option.
  46   46  When compression is turned on, the \fBsavecore\fR(1M) utility writes one file
  47   47  to the file system named \fIvmdump.X\fR. If compression is disabled, it instead
  48   48  writes two files named \fIunix.X\fR and \fIvmcore.X\fR. In the uncompressed
  49   49  case, both data files form the \fIsaved crash dump\fR. In both cases X is an
  50   50  integer identifying the dump.
  51   51  .sp
  52   52  .LP
  53   53  For systems with a UFS root file system, the default dump device is  configured
  54   54  to be an appropriate swap partition. Swap partitions are disk partitions
  55   55  reserved as virtual memory backing store for the operating system. Thus, no
  56   56  permanent information resides in swap to be overwritten by the dump. See
  57   57  \fBswap\fR(1M). For systems with a ZFS root file system, dedicated ZFS volumes
  58   58  are used for swap and dump areas. For further information about setting up a
  59   59  dump area with ZFS,  see the \fIZFS Administration Guide\fR. To view the
  60   60  current dump  configuration, use the \fBdumpadm\fR command with no arguments:
  61   61  .sp
  62   62  .in +2
  63   63  .nf
  64   64  example# \fBdumpadm\fR
  65   65  
  66   66        Dump content: kernel pages
  67   67         Dump device: /dev/dsk/c0t0d0s1 (swap)
  68   68  Savecore directory: /var/crash/saturn
  69   69    Savecore enabled: yes
  70   70     Save compressed: on
  71   71  .fi
  72   72  .in -2
  73   73  .sp
  74   74  
  75   75  .sp
  76   76  .LP
  77   77  When no options are specified, \fBdumpadm\fR prints the current crash dump
  78   78  configuration. The example shows the set of default values: the dump content is
  79   79  set to kernel memory pages only, the dump device is a swap disk partition, the
  80   80  directory for \fBsavecore\fR files is set to
  81   81  \fB/var/crash/\fR\fIhostname\fR\fB,\fR \fBsavecore\fR is set to run
  82   82  automatically on reboot, and compression is turned on.
  83   83  .sp
  84   84  .LP
  85   85  When one or more options are specified, \fBdumpadm\fR verifies that your
  86   86  changes are valid, and if so, reconfigures the crash dump parameters and
  87   87  displays the resulting configuration. You must be \fBroot\fR to view or change
  88   88  dump parameters.
  89   89  .SH OPTIONS
  90   90  .sp
  91   91  .LP
  92   92  The following options are supported:
  93   93  .sp
  94   94  .ne 2
  95   95  .na
  96   96  \fB\fB-c\fR \fIcontent-type\fR\fR
  97   97  .ad
  98   98  .sp .6
  99   99  .RS 4n
 100  100  Modify the dump configuration so that the crash dump consists of the specified
 101  101  dump content. The content should be one of the following:
 102  102  .sp
 103  103  .ne 2
 104  104  .na
 105  105  \fB\fBkernel\fR\fR
 106  106  .ad
 107  107  .sp .6
 108  108  .RS 4n
 109  109  Kernel memory pages only.
 110  110  .RE
 111  111  
 112  112  .sp
 113  113  .ne 2
 114  114  .na
 115  115  \fB\fBall\fR\fR
 116  116  .ad
 117  117  .sp .6
 118  118  .RS 4n
 119  119  All memory pages.
 120  120  .RE
 121  121  
 122  122  .sp
 123  123  .ne 2
 124  124  .na
 125  125  \fB\fBcurproc\fR\fR
 126  126  .ad
 127  127  .sp .6
 128  128  .RS 4n
 129  129  Kernel memory pages, and the memory pages of the process whose thread was
 130  130  currently executing on the CPU on which the crash dump was initiated. If the
 131  131  thread executing on that CPU is a kernel thread not associated with any user
 132  132  process, only kernel pages will be dumped.
 133  133  .RE
 134  134  
 135  135  .RE
 136  136  
 137  137  .sp
 138  138  .ne 2
 139  139  .na
 140  140  \fB\fB-d\fR \fIdump-device\fR\fR
 141  141  .ad
 142  142  .sp .6
 143  143  .RS 4n
 144  144  Modify the dump configuration to use the specified dump device. The dump device
 145  145  may be one of the following:
 146  146  .sp
 147  147  .ne 2
 148  148  .na
 149  149  \fB\fIdump-device\fR\fR
 150  150  .ad
 151  151  .sp .6
 152  152  .RS 4n
 153  153  A specific dump device specified as an absolute pathname, such as
 154  154  \fB/dev/dsk/\fR\fIcNtNdNsN\fR when the system is running a UFS root file
 155  155  system. Or, specify a ZFS volume, such as \fB/dev/zvol/dsk/rpool/dump\fR, when
 156  156  the system is running a ZFS root file system.
 157  157  .RE
 158  158  
 159  159  .sp
 160  160  .ne 2
 161  161  .na
 162  162  \fB\fBswap\fR\fR
 163  163  .ad
 164  164  .sp .6
 165  165  .RS 4n
 166  166  If the special token \fBswap\fR is specified as the dump device, \fBdumpadm\fR
 167  167  examines the  active swap entries and selects the most appropriate entry to
 168  168  configure as the dump device. See \fBswap\fR(1M). Refer to the \fBNOTES\fR
 169  169  below for details of the algorithm  used to select an appropriate swap entry.
 170  170  When the system is first installed with a UFS root file system, \fBdumpadm\fR
 171  171  uses the value for \fBswap\fR to determine the initial dump device setting. A
 172  172  given ZFS volume cannot be configured for both the swap area and the dump
 173  173  device.
 174  174  .RE
 175  175  
 176  176  .sp
 177  177  .ne 2
 178  178  .na

 179  179  \fB\fBnone\fR\fR
 180  180  .ad
 181  181  .sp .6
 182  182  .RS 4n
 183  183  If the special token \fBnone\fR is specified, the active dump device is removed
 184  184  and crash dumps are disabled.
 185  185  .RE
 186  186  
 187  187  .RE
 188  188  
      189 +.sp
      190 +.ne 2
      191 +.na
      192 +\fB\fB-e\fR\fR
      193 +.ad
      194 +.sp .6
      195 +.RS 4n
      196 +Estimates the size of the dump for the current running system.
      197 +.RE
      198 +
 189  199  .sp
 190  200  .ne 2
 191  201  .na
 192  202  \fB\fB-m\fR \fImin\fR\fBk\fR | \fImin\fR\fBm\fR | \fImin\fR\fB%\fR\fR
 193  203  .ad
 194  204  .sp .6
 195  205  .RS 4n
 196  206  Create a \fBminfree\fR file in the current savecore directory indicating that
 197  207  \fBsavecore\fR should maintain at least the specified amount of free space in
 198  208  the file system where the savecore directory is located. The \fBmin\fR argument

 199  209  can be one of the following:
 200  210  .sp
 201  211  .ne 2
 202  212  .na
 203  213  \fB\fBk\fR\fR
 204  214  .ad
 205  215  .sp .6
 206  216  .RS 4n
 207  217  A positive integer suffixed with the unit \fBk\fR specifying kilobytes.
 208  218  .RE
 209  219  
 210  220  .sp
 211  221  .ne 2
 212  222  .na
 213  223  \fB\fBm\fR\fR
 214  224  .ad
 215  225  .sp .6
 216  226  .RS 4n
 217  227  A positive integer suffixed with the unit \fBm\fR specifying megabytes.
 218  228  .RE
 219  229  
 220  230  .sp
 221  231  .ne 2
 222  232  .na
 223  233  \fB\fB%\fR\fR
 224  234  .ad
 225  235  .sp .6
 226  236  .RS 4n
 227  237  A % symbol, indicating that the \fBminfree\fR value should be computed as the
 228  238  specified percentage of the total current size of the file system containing
 229  239  the savecore directory.
 230  240  .RE
 231  241  
 232  242  The \fBsavecore\fR command will consult the \fBminfree\fR file, if present,
 233  243  prior to writing the dump files. If the size of these files would decrease the
 234  244  amount of free disk space below the \fBminfree\fR threshold, no dump files are
 235  245  written and an error message is logged. The administrator should immediately
 236  246  clean up the savecore directory to provide adequate free space, and re-execute
 237  247  the \fBsavecore\fR command manually. The administrator can also specify an
 238  248  alternate directory on the \fBsavecore\fR command-line.
 239  249  .RE
 240  250  
 241  251  .sp
 242  252  .ne 2
 243  253  .na
 244  254  \fB\fB-n\fR\fR
 245  255  .ad
 246  256  .sp .6
 247  257  .RS 4n
 248  258  Modify the dump configuration to not run \fBsavecore\fR automatically on
 249  259  reboot. This is not the recommended system configuration; if the dump device is
 250  260  a swap partition, the dump data will be overwritten as the system begins to
 251  261  swap. If \fBsavecore\fR is not executed shortly after boot, crash dump
 252  262  retrieval may not be possible.
 253  263  .RE
 254  264  
 255  265  .sp
 256  266  .ne 2
 257  267  .na
 258  268  \fB\fB-r\fR \fIroot-dir\fR\fR
 259  269  .ad
 260  270  .sp .6
 261  271  .RS 4n
 262  272  Specify an alternate root directory relative to which \fBdumpadm\fR should
 263  273  create files. If no \fB-r\fR argument is specified, the default root directory
 264  274  \fB/\fR is used.
 265  275  .RE
 266  276  
 267  277  .sp
 268  278  .ne 2
 269  279  .na
 270  280  \fB\fB-s\fR \fIsavecore-dir\fR\fR
 271  281  .ad
 272  282  .sp .6
 273  283  .RS 4n
 274  284  Modify the dump configuration to use the specified directory to save files
 275  285  written by \fBsavecore\fR. The directory should be an absolute path and exist
 276  286  on the system. If upon reboot the directory does not exist, it will be created
 277  287  prior to the execution of \fBsavecore\fR. See the \fBNOTES\fR section below for
 278  288  a discussion of security issues relating to access to the savecore directory.
 279  289  The default savecore directory is \fB/var/crash/\fIhostname\fR\fR where
 280  290  \fIhostname\fR is the output of the \fB-n\fR option to the \fBuname\fR(1)
 281  291  command.
 282  292  .RE
 283  293  
 284  294  .sp
 285  295  .ne 2
 286  296  .na
 287  297  \fB\fB-u\fR\fR
 288  298  .ad
 289  299  .sp .6
 290  300  .RS 4n
 291  301  Forcibly update the kernel dump configuration based on the contents of
 292  302  \fB/etc/dumpadm.conf\fR. Normally this option is used only on reboot when
 293  303  starting \fBsvc:/system/dumpadm:default\fR, when the \fBdumpadm\fR settings
 294  304  from the previous boot must be restored. Your dump configuration is saved in
 295  305  the configuration file for this purpose. If the configuration file is missing
 296  306  or contains invalid values for any dump properties, the default values are
 297  307  substituted. Following the update, the configuration file is resynchronized
 298  308  with the kernel dump configuration.
 299  309  .RE
 300  310  
 301  311  .sp
 302  312  .ne 2
 303  313  .na
 304  314  \fB\fB-y\fR\fR
 305  315  .ad
 306  316  .sp .6
 307  317  .RS 4n
 308  318  Modify the dump configuration to automatically run \fBsavecore\fR on reboot.
 309  319  This is the default for this dump setting.
 310  320  .RE
 311  321  
 312  322  .sp
 313  323  .ne 2
 314  324  .na
 315  325  \fB\fB-z on | off\fR\fR
 316  326  .ad
 317  327  .sp .6
 318  328  .RS 4n
 319  329  Turns crash dump compression \fBon\fR or \fBoff\fR.
 320  330  .RE
 321  331  
 322  332  .SH EXAMPLES
 323  333  .LP
 324  334  \fBExample 1 \fRReconfiguring The Dump Device To A Dedicated Dump Device:
 325  335  .sp
 326  336  .LP
 327  337  The following command reconfigures the dump device to a dedicated dump device:
 328  338  
 329  339  .sp
 330  340  .in +2
 331  341  .nf
 332  342  example# dumpadm -d /dev/dsk/c0t2d0s2
 333  343  
 334  344             Dump content: kernel pages
 335  345              Dump device: /dev/dsk/c0t2d0s2 (dedicated)
 336  346       Savecore directory: /var/crash/saturn
 337  347         Savecore enabled: yes
 338  348          Save compressed: on
 339  349  .fi
 340  350  .in -2
 341  351  .sp
 342  352  
 343  353  .SH EXIT STATUS
 344  354  .sp
 345  355  .LP
 346  356  The following exit values are returned:
 347  357  .sp
 348  358  .ne 2
 349  359  .na
 350  360  \fB\fB0\fR\fR
 351  361  .ad
 352  362  .sp .6
 353  363  .RS 4n
 354  364  Dump configuration is valid and the specified modifications, if any, were made
 355  365  successfully.
 356  366  .RE
 357  367  
 358  368  .sp
 359  369  .ne 2
 360  370  .na
 361  371  \fB\fB1\fR\fR
 362  372  .ad
 363  373  .sp .6
 364  374  .RS 4n
 365  375  A fatal error occurred in either obtaining or modifying the dump configuration.
 366  376  .RE
 367  377  
 368  378  .sp
 369  379  .ne 2
 370  380  .na
 371  381  \fB\fB2\fR\fR
 372  382  .ad
 373  383  .sp .6
 374  384  .RS 4n
 375  385  Invalid command line options were specified.
 376  386  .RE
 377  387  
 378  388  .SH FILES
 379  389  .sp
 380  390  .ne 2
 381  391  .na
 382  392  \fB\fB/dev/dump\fR\fR
 383  393  .ad
 384  394  .sp .6
 385  395  .RS 4n
 386  396  Dump device.
 387  397  .RE
 388  398  
 389  399  .sp
 390  400  .ne 2
 391  401  .na
 392  402  \fB\fB/etc/dumpadm.conf\fR\fR
 393  403  .ad
 394  404  .sp .6
 395  405  .RS 4n
 396  406  Contains configuration parameters for \fBdumpadm\fR. Modifiable only through
 397  407  that command.
 398  408  .RE
 399  409  
 400  410  .sp
 401  411  .ne 2
 402  412  .na
 403  413  \fB\fIsavecore-directory\fR\fB/minfree\fR\fR
 404  414  .ad
 405  415  .sp .6
 406  416  .RS 4n
 407  417  Contains minimum amount of free space for \fIsavecore-directory\fR. See
 408  418  \fBsavecore\fR(1M).
 409  419  .RE
 410  420  
 411  421  .SH SEE ALSO
 412  422  .sp
 413  423  .LP
 414  424  \fBsvcs\fR(1), \fBuname\fR(1), \fBsavecore\fR(1M), \fBsvcadm\fR(1M),
 415  425  \fBswap\fR(1M), \fBattributes\fR(5), \fBsmf\fR(5)
 416  426  .SH NOTES
 417  427  .sp
 418  428  .LP
 419  429  The system crash dump service is managed by the service management facility,
 420  430  \fBsmf\fR(5), under the service identifier:
 421  431  .sp
 422  432  .in +2
 423  433  .nf
 424  434  svc:/system/dumpadm:default
 425  435  .fi
 426  436  .in -2
 427  437  .sp
 428  438  
 429  439  .sp
 430  440  .LP
 431  441  Administrative actions on this service, such as enabling, disabling, or
 432  442  requesting restart, can be performed using \fBsvcadm\fR(1M). The service's
 433  443  status can be queried using the \fBsvcs\fR(1) command.
 434  444  .SS "Dump Device Selection"
 435  445  .sp
 436  446  .LP
 437  447  When the special \fBswap\fR token is specified as the argument to \fBdumpadm\fR
 438  448  \fB-d\fR the utility will attempt to configure the most appropriate swap device
 439  449  as the dump device. \fBdumpadm\fR configures the largest swap block device as
 440  450  the dump device; if no block devices are available for swap, the largest swap
 441  451  entry is configured as the dump device. If no swap entries are present, or none
 442  452  can be configured as the dump device, a warning message will be displayed.
 443  453  While local and remote swap files can be configured as the dump device, this is
 444  454  not recommended.
 445  455  .SS "Dump Device/Swap Device Interaction (UFS File Systems Only)"
 446  456  .sp
 447  457  .LP
 448  458  In the event that the dump device is also a swap device, and the swap device is
 449  459  deleted by the administrator using the \fBswap\fR \fB-d\fR command, the
 450  460  \fBswap\fR command will automatically invoke \fBdumpadm\fR \fB-d\fR \fBswap\fR
 451  461  in order to attempt to configure another appropriate swap device as the dump
 452  462  device. If no swap devices remain or none can be configured as the dump device,
 453  463  the crash dump will be disabled and a warning message will be displayed.
 454  464  Similarly, if the crash dump is disabled and the administrator adds a new swap
 455  465  device using the \fBswap\fR \fB-a\fR command, \fBdumpadm\fR \fB-d\fR \fBswap\fR
 456  466  will be invoked to re-enable the crash dump using the new swap device.
 457  467  .sp
 458  468  .LP
 459  469  Once \fBdumpadm\fR \fB-d\fR \fBswap\fR has been issued, the new dump device is
 460  470  stored in the configuration file for subsequent reboots. If a larger or more
 461  471  appropriate swap device is added by the administrator, the dump device is not
 462  472  changed; the administrator must re-execute \fBdumpadm\fR \fB-d\fR \fBswap\fR to
 463  473  reselect the most appropriate device fom the new list of swap devices.
 464  474  .SS "Minimum Free Space"
 465  475  .sp
 466  476  .LP
 467  477  If the \fBdumpadm\fR \fB-m\fR option is used to create a \fBminfree\fR file
 468  478  based on a percentage of the total size of the file system containing the
 469  479  savecore directory, this value is not automatically recomputed if the file
 470  480  system subsequently changes size.  In this case, the administrator must
 471  481  re-execute \fBdumpadm\fR \fB-m\fR to recompute the \fBminfree\fR value. If no
 472  482  such file exists in the savecore directory, \fBsavecore\fR will default to a
 473  483  free space threshold of one megabyte. If no free space threshold is desired, a
 474  484  minfree file containing size 0 can be created.
 475  485  .SS "Security Issues"
 476  486  .sp
 477  487  .LP
 478  488  If, upon reboot, the specified savecore directory is not present, it will be
 479  489  created prior to the execution of \fBsavecore\fR with permissions 0700 (read,
 480  490  write, execute by owner only) and owner \fBroot\fR. It is recommended that
 481  491  alternate savecore directories also be created with similar permissions, as the
 482  492  operating system crash dump files themselves may contain secure information.

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX