sbin/savecore/savecore.8

   1 .\" Copyright (c) 1980, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     From: @(#)savecore.8    8.1 (Berkeley) 6/5/93
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd April 4, 2022
  32 .Dt SAVECORE 8
  33 .Os
  34 .Sh NAME
  35 .Nm savecore
  36 .Nd "save a core dump of the operating system"
  37 .Sh SYNOPSIS
  38 .Nm
  39 .Fl c
  40 .Op Fl v
  41 .Op Ar device ...
  42 .Nm
  43 .Fl C
  44 .Op Fl v
  45 .Op Ar device ...
  46 .Nm
  47 .Fl L
  48 .Op Fl fvZz
  49 .Op Fl m Ar maxdumps
  50 .Op Ar directory
  51 .Nm
  52 .Op Fl -libxo
  53 .Op Fl fkuvz
  54 .Op Fl m Ar maxdumps
  55 .Op Ar directory Op Ar device ...
  56 .Sh DESCRIPTION
  57 The
  58 .Nm
  59 utility
  60 copies a core dump into
  61 .Ar directory ,
  62 or the current working directory if no
  63 .Ar directory
  64 argument is given,
  65 and enters a reboot message and information about the core dump into
  66 the system log.
  67 .Pp
  68 The options are as follows:
  69 .Bl -tag -width ".Fl m Ar maxdumps"
  70 .It Fl -libxo
  71 Generate output via
  72 .Xr libxo 3
  73 in a selection of different human and machine readable formats.
  74 See
  75 .Xr xo_parse_args 3
  76 for details on command line arguments.
  77 .It Fl C
  78 Check to see if a dump exists,
  79 and display a brief message to indicate the status.
  80 An exit status of 0 indicates that a dump is there,
  81 1 indicates that none exists.
  82 This option is compatible only with the
  83 .Op Fl v
  84 option.
  85 .It Fl c
  86 Clear the dump, so that future invocations of
  87 .Nm
  88 will ignore it.
  89 .It Fl f
  90 Force a dump to be taken even if either the dump was cleared or if the
  91 dump header information is inconsistent.
  92 .It Fl k
  93 Do not clear the dump after saving it.
  94 .It Fl L
  95 Instruct
  96 .Nm
  97 to generate and save a kernel dump of the running system, rather than
  98 copying one from a dump device.
  99 .It Fl m Ar maxdumps
 100 Maximum number of dumps to store.
 101 Once the number of stored dumps is equal to
 102 .Ar maxdumps
 103 the counter will restart from
 104 .Dv 0 .
 105 .It Fl u
 106 Uncompress the dump in case it was compressed by the kernel.
 107 .It Fl v
 108 Print out some additional debugging information.
 109 Specify twice for more information.
 110 .It Fl Z
 111 Compress the dump (see
 112 .Xr zstd 1 ) .
 113 This option is only supported in conjunction with the
 114 .Fl L
 115 option.
 116 Regular dumps can be configured for compression with zstd using
 117 .Xr dumpon 8 .
 118 .It Fl z
 119 Compress the dump (see
 120 .Xr gzip 1 ) .
 121 The dump may already be compressed if the kernel was configured to
 122 do so by
 123 .Xr dumpon 8 .
 124 In this case, the option has no effect.
 125 .Pp
 126 If used in conjunction with the
 127 .Fl L
 128 option, the requested live dump will be compressed with gzip.
 129 .El
 130 .Pp
 131 The
 132 .Nm
 133 utility
 134 looks for dumps on each device specified by the
 135 .Ar device
 136 argument(s), or on each device in
 137 .Pa /etc/fstab
 138 marked as
 139 .Dq dump
 140 or
 141 .Dq swap .
 142 The
 143 .Nm
 144 utility
 145 checks the core dump in various ways to make sure that it is complete.
 146 If it passes these checks, it saves the core image in
 147 .Ar directory Ns Pa /vmcore.#
 148 and information about the core in
 149 .Ar directory Ns Pa /info.# .
 150 If the core is encrypted, it saves the dump key in
 151 .Ar directory Ns Pa /key.# .
 152 The core can be later decrypted using
 153 .Xr decryptcore 8 .
 154 For kernel textdumps generated with the
 155 .Xr textdump 4
 156 facility, output will be stored in the
 157 .Xr tar 5
 158 format and named
 159 .Ar directory Ns Pa /textdump.tar.# .
 160 The
 161 .Dq #
 162 is the number from the first line of the file
 163 .Ar directory Ns Pa /bounds ,
 164 and it is incremented and stored back into the file each time
 165 .Nm
 166 successfully runs.
 167 .Pp
 168 The
 169 .Nm
 170 utility
 171 also checks the available disk space before attempting to make the copies.
 172 If there is insufficient disk space in the file system containing
 173 .Ar directory ,
 174 or if the file
 175 .Ar directory Ns Pa /minfree
 176 exists and the number of free kilobytes (for non-superusers) in the
 177 file system after the copies were made would be less than the number
 178 in the first line of this file, the copies are not attempted.
 179 .Pp
 180 If
 181 .Nm
 182 successfully copies the kernel and the core dump, the core dump is cleared
 183 so that future invocations of
 184 .Nm
 185 will ignore it.
 186 .Pp
 187 The
 188 .Nm
 189 utility
 190 is meant to be called near the end of the initialization file
 191 .Pa /etc/rc
 192 (see
 193 .Xr rc 8 ) .
 194 .Sh SEE ALSO
 195 .Xr gzip 1 ,
 196 .Xr zstd 1 ,
 197 .Xr getbootfile 3 ,
 198 .Xr libxo 3 ,
 199 .Xr xo_parse_args 3 ,
 200 .Xr mem 4 ,
 201 .Xr textdump 4 ,
 202 .Xr tar 5 ,
 203 .Xr crashinfo 8 ,
 204 .Xr decryptcore 8 ,
 205 .Xr dumpon 8 ,
 206 .Xr syslogd 8
 207 .Sh HISTORY
 208 The
 209 .Nm
 210 utility appeared in
 211 .Bx 4.1 .
 212 .Pp
 213 Support for kernel textdumps appeared in
 214 .Fx 7.1 .
 215 .Sh BUGS
 216 The minfree code does not consider the effect of compression or sparse files.