xref: /freebsd/sbin/savecore/savecore.8 (revision 5ca8e32633c4ffbbcd6762e5888b6a4ba0708c6c)
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.Dd April 4, 2022
29.Dt SAVECORE 8
30.Os
31.Sh NAME
32.Nm savecore
33.Nd "save a core dump of the operating system"
34.Sh SYNOPSIS
35.Nm
36.Fl c
37.Op Fl v
38.Op Ar device ...
39.Nm
40.Fl C
41.Op Fl v
42.Op Ar device ...
43.Nm
44.Fl L
45.Op Fl fvZz
46.Op Fl m Ar maxdumps
47.Op Ar directory
48.Nm
49.Op Fl -libxo
50.Op Fl fkuvz
51.Op Fl m Ar maxdumps
52.Op Ar directory Op Ar device ...
53.Sh DESCRIPTION
54The
55.Nm
56utility
57copies a core dump into
58.Ar directory ,
59or the current working directory if no
60.Ar directory
61argument is given,
62and enters a reboot message and information about the core dump into
63the system log.
64.Pp
65The options are as follows:
66.Bl -tag -width ".Fl m Ar maxdumps"
67.It Fl -libxo
68Generate output via
69.Xr libxo 3
70in a selection of different human and machine readable formats.
71See
72.Xr xo_parse_args 3
73for details on command line arguments.
74.It Fl C
75Check to see if a dump exists,
76and display a brief message to indicate the status.
77An exit status of 0 indicates that a dump is there,
781 indicates that none exists.
79This option is compatible only with the
80.Op Fl v
81option.
82.It Fl c
83Clear the dump, so that future invocations of
84.Nm
85will ignore it.
86.It Fl f
87Force a dump to be taken even if either the dump was cleared or if the
88dump header information is inconsistent.
89.It Fl k
90Do not clear the dump after saving it.
91.It Fl L
92Instruct
93.Nm
94to generate and save a kernel dump of the running system, rather than
95copying one from a dump device.
96.It Fl m Ar maxdumps
97Maximum number of dumps to store.
98Once the number of stored dumps is equal to
99.Ar maxdumps
100the counter will restart from
101.Dv 0 .
102.It Fl u
103Uncompress the dump in case it was compressed by the kernel.
104.It Fl v
105Print out some additional debugging information.
106Specify twice for more information.
107.It Fl Z
108Compress the dump (see
109.Xr zstd 1 ) .
110This option is only supported in conjunction with the
111.Fl L
112option.
113Regular dumps can be configured for compression with zstd using
114.Xr dumpon 8 .
115.It Fl z
116Compress the dump (see
117.Xr gzip 1 ) .
118The dump may already be compressed if the kernel was configured to
119do so by
120.Xr dumpon 8 .
121In this case, the option has no effect.
122.Pp
123If used in conjunction with the
124.Fl L
125option, the requested live dump will be compressed with gzip.
126.El
127.Pp
128The
129.Nm
130utility
131looks for dumps on each device specified by the
132.Ar device
133argument(s), or on each device in
134.Pa /etc/fstab
135marked as
136.Dq dump
137or
138.Dq swap .
139The
140.Nm
141utility
142checks the core dump in various ways to make sure that it is complete.
143If it passes these checks, it saves the core image in
144.Ar directory Ns Pa /vmcore.#
145and information about the core in
146.Ar directory Ns Pa /info.# .
147If the core is encrypted, it saves the dump key in
148.Ar directory Ns Pa /key.# .
149The core can be later decrypted using
150.Xr decryptcore 8 .
151For kernel textdumps generated with the
152.Xr textdump 4
153facility, output will be stored in the
154.Xr tar 5
155format and named
156.Ar directory Ns Pa /textdump.tar.# .
157The
158.Dq #
159is the number from the first line of the file
160.Ar directory Ns Pa /bounds ,
161and it is incremented and stored back into the file each time
162.Nm
163successfully runs.
164.Pp
165The
166.Nm
167utility
168also checks the available disk space before attempting to make the copies.
169If there is insufficient disk space in the file system containing
170.Ar directory ,
171or if the file
172.Ar directory Ns Pa /minfree
173exists and the number of free kilobytes (for non-superusers) in the
174file system after the copies were made would be less than the number
175in the first line of this file, the copies are not attempted.
176.Pp
177If
178.Nm
179successfully copies the kernel and the core dump, the core dump is cleared
180so that future invocations of
181.Nm
182will ignore it.
183.Pp
184The
185.Nm
186utility
187is meant to be called near the end of the initialization file
188.Pa /etc/rc
189(see
190.Xr rc 8 ) .
191.Sh SEE ALSO
192.Xr gzip 1 ,
193.Xr zstd 1 ,
194.Xr getbootfile 3 ,
195.Xr libxo 3 ,
196.Xr xo_parse_args 3 ,
197.Xr mem 4 ,
198.Xr textdump 4 ,
199.Xr tar 5 ,
200.Xr crashinfo 8 ,
201.Xr decryptcore 8 ,
202.Xr dumpon 8 ,
203.Xr syslogd 8
204.Sh HISTORY
205The
206.Nm
207utility appeared in
208.Bx 4.1 .
209.Pp
210Support for kernel textdumps appeared in
211.Fx 7.1 .
212.Sh BUGS
213The minfree code does not consider the effect of compression or sparse files.
214