Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
dumpadm(1M)		System Administration Commands		   dumpadm(1M)

       dumpadm - configure operating system crash dump

       /usr/sbin/dumpadm  [-nuy] [-c content-type] [-d dump-device] [-m	mink |
       minm  |	min%]  [-s savecore-dir] [-r root-dir]

       The dumpadm program is an administrative	command	that manages the  con-
       figuration  of  the operating system crash dump facility.  A crash dump
       is a disk copy of the physical memory of	the computer at	the time of  a
       fatal  system error. When a fatal operating system error	occurs,	a mes-
       sage describing the error is printed to the console. The	operating sys-
       tem  then  generates  a	crash dump by writing the contents of physical
       memory to a predetermined dump device, which is typically a local  disk
       partition.   The	 dump device can be configured by way of dumpadm. Once
       the crash dump has been written to the dump device, the system will re-

       Fatal  operating	 system	 errors	can be caused by bugs in the operating
       system, its associated device  drivers  and  loadable  modules,	or  by
       faulty hardware.	Whatever the cause, the	crash dump itself provides in-
       valuable	information to your support engineer to	aid in diagnosing  the
       problem.	  As  such,  it	 is vital that the crash dump be retrieved and
       given to	your support provider. Following an  operating	system	crash,
       the  savecore(1M)  utility is executed automatically during boot	to re-
       trieve the crash	dump from the dump device, and write it	to a  pair  of
       files  in your file system named	unix.X and vmcore.X, where X is	an in-
       teger identifying the dump. Together, these data	files form  the	 saved
       crash  dump.  The  directory in which the crash dump is saved on	reboot
       can also	be configured using dumpadm.

       By default, the dump device is configured to  be	 an  appropriate  swap
       partition. Swap partitions are disk partitions reserved as virtual mem-
       ory backing store for the operating system, and thus no	permanent  in-
       formation resides there to be overwritten by the	dump. See swap(1M). To
       view the	current	dump configuration, execute dumpadm with no arguments:

       example#	dumpadm

	     Dump content: kernel pages
	      Dump device: /dev/dsk/c0t0d0s1 (swap)
       Savecore	directory: /var/crash/saturn
	 Savecore enabled: yes

       When no options are specified, dumpadm prints the  current  crash  dump
       configuration.	The  example shows the set of default values: the dump
       content is set to kernel	memory pages only, the dump device is  a  swap
       disk   partition,   the	 directory   for  savecore  files  is  set  to
       /var/crash/hostname, and	savecore is set	to run	automatically  on  re-

       When  one  or  more  options  are specified, dumpadm verifies that your
       changes are valid, and if so, reconfigures the  crash  dump  parameters
       and  displays  the resulting configuration. You must be root to view or
       change dump parameters.

       The following options are supported:

       -c content-type
	     Modify the	dump configuration so that the crash dump consists  of
	     the  specified  dump  content.   The content should be one	of the

		   Kernel memory pages only.

	     all   All memory pages.

		   Kernel memory pages,	and the	memory pages  of  the  process
		   whose  thread  was  currently executing on the CPU on which
		   the crash dump was initiated. If the	 thread	 executing  on
		   that	 CPU  is  a kernel thread not associated with any user
		   process, only kernel	pages will be dumped.

       -d  dump-device
	     Modify the	dump configuration to use the specified	 dump  device.
	     The dump device may one of	the following:

		   A  specific	dump device specified as an absolute pathname,
		   such	as /dev/dsk/ cNtNdNsN.

	     swap  If the special token	swap is	specified as the dump  device,
		   dumpadm  examines  the  active swap entries and selects the
		   most	appropriate entry  to configure	as  the	 dump  device.
		   See	 swap(1M).  Refer  to the  NOTES  below	for details of
		   the algorithm used to select	 an  appropriate  swap	entry.
		   When	 the  system  is first installed, dumpadm uses swap to
		   determine the initial dump device setting.

       -m mink | minm |	min%
	     Create a minfree file in the current savecore directory  indicat-
	     ing  that	savecore should	maintain at least the specified	amount
	     of	free space in the file system where the	savecore directory  is
	     located.  The min argument	can be one of the following:

	     k	   A  positive	integer	 suffixed  with	 the unit k specifying

	     m	   A positive integer suffixed	with  the  unit	 m  specifying

	     %	   A  %	 symbol,  indicating  that the minfree value should be
		   computed as the specified percentage	of the	total  current
		   size	of the file system containing the savecore directory.

       The  savecore  command will consult the minfree file, if	present, prior
       to writing the dump files.  If the size of these	files  would  decrease
       the  amount  of	free  disk  space below	the minfree threshold, no dump
       files are written and an	error message is  logged.   The	 administrator
       should  immediately clean up the	savecore directory to provide adequate
       free space, and re-execute the savecore command manually.  The adminis-
       trator can also specify an alternate directory on the savecore command-

       -n    Modify the	dump configuration to not run  savecore	 automatically
	     on	 reboot.  This is not the recommended system configuration; if
	     the dump device is	a swap partition, the dump data	will be	 over-
	     written  as  the  system begins to	swap.  If savecore is not exe-
	     cuted shortly after boot, crash dump retrieval may	not be	possi-

       -r root-dir
	     Specify  an  alternate  root  directory relative to which dumpadm
	     should create files.  If no -r argument is	specified, the default
	     root directory "/"	is used.

       -s savecore-dir
	     Modify  the  dump configuration to	use the	specified directory to
	     save files	written	by savecore. The directory should be an	 abso-
	     lute  path	and exist on the system.  If upon reboot the directory
	     does not exist, it	will be	created	 prior	to  the	 execution  of
	     savecore.	See the	 NOTES section below for a discussion of secu-
	     rity issues relating to access to the  savecore  directory.   The
	     default  savecore	directory is /var/crash/hostname where	is the
	     output of the -n option to	the uname(1) command.

       -u    Forcibly update the kernel	dump configuration based on  the  con-
	     tents  of /etc/dumpadm.conf. Normally this	option is used only on
	     reboot by	the  startup  script  /etc/init.d/savecore,  when  the
	     dumpadm  settings	from the previous boot must be restored.  Your
	     dump configuration	is saved in the	configuration  file  for  this
	     purpose.	If  the	 configuration file is missing or contains in-
	     valid values for any dump properties, the default values are sub-
	     stituted.	Following the update, the configuration	file is	resyn-
	     chronized with the	kernel dump configuration.

       -y    Modify the	dump configuration to automatically  run  savecore  on
	     reboot.  This is the default for this dump	setting.

       Example 1: Reconfiguring	The Dump Device	To A Dedicated Dump Device:

       The  following command reconfigures the dump device to a	dedicated dump

       example#	dumpadm	-d /dev/dsk/c0t2d0s2

		  Dump content:	kernel pages
		   Dump	device:	/dev/dsk/c0t2d0s2 (dedicated)
	    Savecore directory:	/var/crash/saturn
	      Savecore enabled:	yes

       The following exit values are returned:

       0     Dump configuration	is valid and the specified  modifications,  if
	     any, were made successfully.

       1     A	fatal error occurred in	either obtaining or modifying the dump

       2     Invalid command line options were specified.





       See attributes(5) for descriptions of the following attributes:

       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |Availability		     |SUNWcsr			   |

       uname(1), savecore(1M), swap(1M), attributes(5)

   Dump	Device Selection
       When the	special	swap token is specified	as the argument	to dumpadm  -d
       the  utility will attempt to configure the most appropriate swap	device
       as the dump device. dumpadm configures the largest swap block device as
       the  dump  device;  if  no  block  devices  are available for swap, the
       largest swap entry is configured	as the dump device.  If	 no  swap  en-
       tries  are  present,  or	 none  can be configured as the	dump device, a
       warning message will be displayed.  While local and remote  swap	 files
       can be configured as the	dump device, this is not recommended.

   Dump	Device/Swap Device Interaction
       In  the	event that the dump device is also a swap device, and the swap
       device is deleted by the	administrator using the	swap -d	 command,  the
       swap  command will automatically	invoke dumpadm -d swap in order	to at-
       tempt to	configure another appropriate swap device as the dump  device.
       If no swap devices remain or none can be	configured as the dump device,
       the crash dump will be disabled and a  warning  message	will  be  dis-
       played.	Similarly, if the crash	dump is	disabled and the administrator
       adds a new swap device using the	 swap -a command, dumpadm -d swap will
       be invoked to re-enable the crash dump using the	new swap device.

       Once  dumpadm -d	swap has been issued, the new dump device is stored in
       the configuration file for subsequent reboots. If a larger or more  ap-
       propriate swap device is	added by the administrator, the	dump device is
       not changed; the	administrator must re-execute dumpadm -d swap to rese-
       lect the	most appropriate device	fom the	new list of swap devices.

   Minimum Free	Space
       If  the	dumpadm	 -m option is used to create a minfree file based on a
       percentage of the total size of the file	system containing the savecore
       directory,  this	value is not automatically recomputed if the file sys-
       tem subsequently	changes	size.  In this case,  the  administrator  must
       re-execute  dumpadm -m to recompute the minfree value.  If no such file
       exists in the savecore directory, savecore will default to a free space
       threshold  of  one  megabyte.  If no free space threshold is desired, a
       minfree file containing size 0 can be created.

   Security Issues
       If, upon	reboot,	the specified savecore directory is  not  present,  it
       will  be	 created  prior	 to the	execution of savecore with permissions
       0700 (read, write, execute by owner only) and owner root. It is	recom-
       mended that alternate savecore directories also be created with similar
       permissions, as the operating system crash dump	files  themselves  may
       contain secure information.

SunOS 5.9			3 October 2000			   dumpadm(1M)


Want to link to this manual page? Use this URL:

home | help