xref: /freebsd/sys/ddb/db_textdump.c (revision 9f23cbd6cae82fd77edfad7173432fa8dccd0a95)
1 /*-
2  * SPDX-License-Identifier: BSD-2-Clause
3  *
4  * Copyright (c) 2007 Robert N. M. Watson
5  * All rights reserved.
6  *
7  * Redistribution and use in source and binary forms, with or without
8  * modification, are permitted provided that the following conditions
9  * are met:
10  * 1. Redistributions of source code must retain the above copyright
11  *    notice, this list of conditions and the following disclaimer.
12  * 2. Redistributions in binary form must reproduce the above copyright
13  *    notice, this list of conditions and the following disclaimer in the
14  *    documentation and/or other materials provided with the distribution.
15  *
16  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 AUTHOR 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 
29 /*-
30  * Kernel text-dump support: write a series of text files to the dump
31  * partition for later recovery, including captured DDB output, kernel
32  * configuration, message buffer, and panic message.  This allows for a more
33  * compact representation of critical debugging information than traditional
34  * binary dumps, as well as allowing dump information to be used without
35  * access to kernel symbols, source code, etc.
36  *
37  * Storage Layout
38  * --------------
39  *
40  * Crash dumps are aligned to the end of the dump or swap partition in order
41  * to minimize the chances of swap duing fsck eating into the dump.  However,
42  * unlike a memory dump, we don't know the size of the textdump a priori, so
43  * can't just write it out sequentially in order from a known starting point
44  * calculated with respect to the end of the partition.  In order to address
45  * this, we actually write out the textdump in reverse block order, allowing
46  * us to directly align it to the end of the partition and then write out the
47  * dump header and trailer before and after it once done.  savecore(8) must
48  * know to reverse the order of the blocks in order to produce a readable
49  * file.
50  *
51  * Data is written out in the ustar file format so that we can write data
52  * incrementally as a stream without reference to previous files.
53  *
54  * TODO
55  * ----
56  *
57  * - Allow subsystems to register to submit files for inclusion in the text
58  *   dump in a generic way.
59  */
60 
61 #include <sys/cdefs.h>
62 __FBSDID("$FreeBSD$");
63 
64 #include "opt_config.h"
65 
66 #include "opt_ddb.h"
67 
68 #include <sys/param.h>
69 #include <sys/conf.h>
70 #include <sys/kernel.h>
71 #include <sys/kerneldump.h>
72 #include <sys/msgbuf.h>
73 #include <sys/sysctl.h>
74 #include <sys/systm.h>
75 
76 #include <ddb/ddb.h>
77 #include <ddb/db_lex.h>
78 
79 static SYSCTL_NODE(_debug_ddb, OID_AUTO, textdump,
80     CTLFLAG_RW | CTLFLAG_MPSAFE, 0,
81     "DDB textdump options");
82 
83 /*
84  * Don't touch the first SIZEOF_METADATA bytes on the dump device.  This is
85  * to protect us from metadata and metadata from us.
86  */
87 #define	SIZEOF_METADATA		(64*1024)
88 
89 /*
90  * Data is written out as a series of files in the ustar tar format.  ustar
91  * is a simple streamed format consiting of a series of files prefixed with
92  * headers, and all padded to 512-byte block boundaries, which maps
93  * conveniently to our requirements.
94  */
95 struct ustar_header {
96 	char	uh_filename[100];
97 	char	uh_mode[8];
98 	char	uh_tar_owner[8];
99 	char	uh_tar_group[8];
100 	char	uh_size[12];
101 	char	uh_mtime[12];
102 	char	uh_sum[8];
103 	char	uh_type;
104 	char	uh_linkfile[100];
105 	char	uh_ustar[6];
106 	char	uh_version[2];
107 	char	uh_owner[32];
108 	char	uh_group[32];
109 	char	uh_major[8];
110 	char	uh_minor[8];
111 	char	uh_filenameprefix[155];
112 	char	uh_zeropad[12];
113 } __packed;
114 
115 /*
116  * Various size assertions -- pretty much everything must be one block in
117  * size.
118  */
119 CTASSERT(sizeof(struct kerneldumpheader) == TEXTDUMP_BLOCKSIZE);
120 CTASSERT(sizeof(struct ustar_header) == TEXTDUMP_BLOCKSIZE);
121 
122 /*
123  * Is a textdump scheduled?  If so, the shutdown code will invoke our dumpsys
124  * routine instead of the machine-dependent kernel dump routine.
125  */
126 #ifdef TEXTDUMP_PREFERRED
127 int	textdump_pending = 1;
128 #else
129 int	textdump_pending = 0;
130 #endif
131 SYSCTL_INT(_debug_ddb_textdump, OID_AUTO, pending, CTLFLAG_RW,
132     &textdump_pending, 0,
133     "Perform textdump instead of regular kernel dump.");
134 
135 /*
136  * Various constants for tar headers and contents.
137  */
138 #define	TAR_USER	"root"
139 #define	TAR_GROUP	"wheel"
140 #define	TAR_UID		"0"
141 #define	TAR_GID		"0"
142 #define	TAR_MODE	"0600"
143 #define	TAR_USTAR	"ustar"
144 
145 #define	TAR_CONFIG_FILENAME	"config.txt"	/* Kernel configuration. */
146 #define	TAR_MSGBUF_FILENAME	"msgbuf.txt"	/* Kernel messsage buffer. */
147 #define	TAR_PANIC_FILENAME	"panic.txt"	/* Panic message. */
148 #define	TAR_VERSION_FILENAME	"version.txt"	/* Kernel version. */
149 
150 /*
151  * Configure which files will be dumped.
152  */
153 #ifdef INCLUDE_CONFIG_FILE
154 static int textdump_do_config = 1;
155 SYSCTL_INT(_debug_ddb_textdump, OID_AUTO, do_config, CTLFLAG_RW,
156     &textdump_do_config, 0, "Dump kernel configuration in textdump");
157 #endif
158 
159 static int textdump_do_ddb = 1;
160 SYSCTL_INT(_debug_ddb_textdump, OID_AUTO, do_ddb, CTLFLAG_RW,
161     &textdump_do_ddb, 0, "Dump DDB captured output in textdump");
162 
163 static int textdump_do_msgbuf = 1;
164 SYSCTL_INT(_debug_ddb_textdump, OID_AUTO, do_msgbuf, CTLFLAG_RW,
165     &textdump_do_msgbuf, 0, "Dump kernel message buffer in textdump");
166 
167 static int textdump_do_panic = 1;
168 SYSCTL_INT(_debug_ddb_textdump, OID_AUTO, do_panic, CTLFLAG_RW,
169     &textdump_do_panic, 0, "Dump kernel panic message in textdump");
170 
171 static int textdump_do_version = 1;
172 SYSCTL_INT(_debug_ddb_textdump, OID_AUTO, do_version, CTLFLAG_RW,
173     &textdump_do_version, 0, "Dump kernel version string in textdump");
174 
175 /*
176  * State related to incremental writing of blocks to disk.
177  */
178 static off_t textdump_offset;		/* Offset of next sequential write. */
179 static int textdump_error;		/* Carried write error, if any. */
180 
181 /*
182  * Statically allocate space to prepare block-sized headers and data.
183  */
184 char textdump_block_buffer[TEXTDUMP_BLOCKSIZE];
185 static struct kerneldumpheader kdh;
186 
187 /*
188  * Calculate and fill in the checksum for a ustar header.
189  */
190 static void
191 ustar_checksum(struct ustar_header *uhp)
192 {
193 	u_int sum;
194 	int i;
195 
196 	for (i = 0; i < sizeof(uhp->uh_sum); i++)
197 		uhp->uh_sum[i] = ' ';
198 	sum = 0;
199 	for (i = 0; i < sizeof(*uhp); i++)
200 		sum += ((u_char *)uhp)[i];
201 	snprintf(uhp->uh_sum, sizeof(uhp->uh_sum), "%6o", sum);
202 }
203 
204 /*
205  * Each file in the tarball has a block-sized header with its name and other,
206  * largely hard-coded, properties.
207  */
208 void
209 textdump_mkustar(char *block_buffer, const char *filename, u_int size)
210 {
211 	struct ustar_header *uhp;
212 
213 #ifdef TEXTDUMP_VERBOSE
214 	if (textdump_error == 0)
215 		printf("textdump: creating '%s'.\n", filename);
216 #endif
217 	uhp = (struct ustar_header *)block_buffer;
218 	bzero(uhp, sizeof(*uhp));
219 	strlcpy(uhp->uh_filename, filename, sizeof(uhp->uh_filename));
220 	strlcpy(uhp->uh_mode, TAR_MODE, sizeof(uhp->uh_mode));
221 	snprintf(uhp->uh_size, sizeof(uhp->uh_size), "%o", size);
222 	strlcpy(uhp->uh_tar_owner, TAR_UID, sizeof(uhp->uh_tar_owner));
223 	strlcpy(uhp->uh_tar_group, TAR_GID, sizeof(uhp->uh_tar_group));
224 	strlcpy(uhp->uh_owner, TAR_USER, sizeof(uhp->uh_owner));
225 	strlcpy(uhp->uh_group, TAR_GROUP, sizeof(uhp->uh_group));
226 	snprintf(uhp->uh_mtime, sizeof(uhp->uh_mtime), "%lo",
227 	    (unsigned long)time_second);
228 	uhp->uh_type = 0;
229 	strlcpy(uhp->uh_ustar, TAR_USTAR, sizeof(uhp->uh_ustar));
230 	ustar_checksum(uhp);
231 }
232 
233 /*
234  * textdump_writeblock() writes TEXTDUMP_BLOCKSIZE-sized blocks of data to
235  * the space between di->mediaoffset and di->mediaoffset + di->mediasize.  It
236  * accepts an offset relative to di->mediaoffset.  If we're carrying any
237  * error from previous I/O, return that error and don't continue to try to
238  * write.  Most writers ignore the error and forge ahead on the basis that
239  * there's not much you can do.
240  */
241 static int
242 textdump_writeblock(struct dumperinfo *di, off_t offset, char *buffer)
243 {
244 
245 	if (textdump_error)
246 		return (textdump_error);
247 	if (offset + TEXTDUMP_BLOCKSIZE > di->mediasize)
248 		return (EIO);
249 	if (offset < SIZEOF_METADATA)
250 		return (ENOSPC);
251 	textdump_error = dump_write(di, buffer, offset + di->mediaoffset,
252 	    TEXTDUMP_BLOCKSIZE);
253 	if (textdump_error)
254 		printf("textdump_writeblock: offset %jd, error %d\n", (intmax_t)offset,
255 		    textdump_error);
256 	return (textdump_error);
257 }
258 
259 /*
260  * Interfaces to save and restore the dump offset, so that printers can go
261  * back to rewrite a header if required, while avoiding their knowing about
262  * the global layout of the blocks.
263  *
264  * If we ever want to support writing textdumps to tape or other
265  * stream-oriented target, we'll need to remove this.
266  */
267 void
268 textdump_saveoff(off_t *offsetp)
269 {
270 
271 	*offsetp = textdump_offset;
272 }
273 
274 void
275 textdump_restoreoff(off_t offset)
276 {
277 
278 	textdump_offset = offset;
279 }
280 
281 /*
282  * Interface to write the "next block" relative to the current offset; since
283  * we write backwards from the end of the partition, we subtract, but there's
284  * no reason for the caller to know this.
285  */
286 int
287 textdump_writenextblock(struct dumperinfo *di, char *buffer)
288 {
289 	int error;
290 
291 	error = textdump_writeblock(di, textdump_offset, buffer);
292 	textdump_offset -= TEXTDUMP_BLOCKSIZE;
293 	return (error);
294 }
295 
296 #ifdef INCLUDE_CONFIG_FILE
297 extern char kernconfstring[];
298 
299 /*
300  * Dump kernel configuration.
301  */
302 static void
303 textdump_dump_config(struct dumperinfo *di)
304 {
305 	u_int count, fullblocks, len;
306 
307 	len = strlen(kernconfstring);
308 	textdump_mkustar(textdump_block_buffer, TAR_CONFIG_FILENAME, len);
309 	(void)textdump_writenextblock(di, textdump_block_buffer);
310 
311 	/*
312 	 * Write out all full blocks directly from the string, and handle any
313 	 * left-over bits by copying it to out to the local buffer and
314 	 * zero-padding it.
315 	 */
316 	fullblocks = len / TEXTDUMP_BLOCKSIZE;
317 	for (count = 0; count < fullblocks; count++)
318 		(void)textdump_writenextblock(di, kernconfstring + count *
319 		    TEXTDUMP_BLOCKSIZE);
320 	if (len % TEXTDUMP_BLOCKSIZE != 0) {
321 		bzero(textdump_block_buffer, TEXTDUMP_BLOCKSIZE);
322 		bcopy(kernconfstring + count * TEXTDUMP_BLOCKSIZE,
323 		    textdump_block_buffer, len % TEXTDUMP_BLOCKSIZE);
324 		(void)textdump_writenextblock(di, textdump_block_buffer);
325 	}
326 }
327 #endif /* INCLUDE_CONFIG_FILE */
328 
329 /*
330  * Dump kernel message buffer.
331  */
332 static void
333 textdump_dump_msgbuf(struct dumperinfo *di)
334 {
335 	off_t end_offset, tarhdr_offset;
336 	u_int i, len, offset, seq, total_len;
337 	char buf[16];
338 
339 	/*
340 	 * Write out a dummy tar header to advance the offset; we'll rewrite
341 	 * it later once we know the true size.
342 	 */
343 	textdump_saveoff(&tarhdr_offset);
344 	textdump_mkustar(textdump_block_buffer, TAR_MSGBUF_FILENAME, 0);
345 	(void)textdump_writenextblock(di, textdump_block_buffer);
346 
347 	/*
348 	 * Copy out the data in small chunks, but don't copy nuls that may be
349 	 * present if the message buffer has not yet completely filled at
350 	 * least once.
351 	 */
352 	total_len = 0;
353 	offset = 0;
354 	msgbuf_peekbytes(msgbufp, NULL, 0, &seq);
355 	while ((len = msgbuf_peekbytes(msgbufp, buf, sizeof(buf), &seq)) > 0) {
356 		for (i = 0; i < len; i++) {
357 			if (buf[i] == '\0')
358 				continue;
359 			textdump_block_buffer[offset] = buf[i];
360 			offset++;
361 			if (offset != sizeof(textdump_block_buffer))
362 				continue;
363 			(void)textdump_writenextblock(di,
364 			    textdump_block_buffer);
365 			total_len += offset;
366 			offset = 0;
367 		}
368 	}
369 	total_len += offset;	/* Without the zero-padding. */
370 	if (offset != 0) {
371 		bzero(textdump_block_buffer + offset,
372 		    sizeof(textdump_block_buffer) - offset);
373 		(void)textdump_writenextblock(di, textdump_block_buffer);
374 	}
375 
376 	/*
377 	 * Rewrite tar header to reflect how much was actually written.
378 	 */
379 	textdump_saveoff(&end_offset);
380 	textdump_restoreoff(tarhdr_offset);
381 	textdump_mkustar(textdump_block_buffer, TAR_MSGBUF_FILENAME,
382 	    total_len);
383 	(void)textdump_writenextblock(di, textdump_block_buffer);
384 	textdump_restoreoff(end_offset);
385 }
386 
387 static void
388 textdump_dump_panic(struct dumperinfo *di)
389 {
390 	u_int len;
391 
392 	/*
393 	 * Write out tar header -- we store up to one block of panic message.
394 	 */
395 	len = min(strlen(panicstr), TEXTDUMP_BLOCKSIZE);
396 	textdump_mkustar(textdump_block_buffer, TAR_PANIC_FILENAME, len);
397 	(void)textdump_writenextblock(di, textdump_block_buffer);
398 
399 	/*
400 	 * Zero-pad the panic string and write out block.
401 	 */
402 	bzero(textdump_block_buffer, sizeof(textdump_block_buffer));
403 	bcopy(panicstr, textdump_block_buffer, len);
404 	(void)textdump_writenextblock(di, textdump_block_buffer);
405 }
406 
407 static void
408 textdump_dump_version(struct dumperinfo *di)
409 {
410 	u_int len;
411 
412 	/*
413 	 * Write out tar header -- at most one block of version information.
414 	 */
415 	len = min(strlen(version), TEXTDUMP_BLOCKSIZE);
416 	textdump_mkustar(textdump_block_buffer, TAR_VERSION_FILENAME, len);
417 	(void)textdump_writenextblock(di, textdump_block_buffer);
418 
419 	/*
420 	 * Zero pad the version string and write out block.
421 	 */
422 	bzero(textdump_block_buffer, sizeof(textdump_block_buffer));
423 	bcopy(version, textdump_block_buffer, len);
424 	(void)textdump_writenextblock(di, textdump_block_buffer);
425 }
426 
427 /*
428  * Commit text dump to disk.
429  */
430 void
431 textdump_dumpsys(struct dumperinfo *di)
432 {
433 	struct kerneldumpcrypto *kdc;
434 	off_t dumplen, trailer_offset;
435 
436 	if (di->blocksize != TEXTDUMP_BLOCKSIZE) {
437 		printf("Dump partition block size (%ju) not textdump "
438 		    "block size (%ju)", (uintmax_t)di->blocksize,
439 		    (uintmax_t)TEXTDUMP_BLOCKSIZE);
440 		return;
441 	}
442 
443 	/*
444 	 * We don't know a priori how large the dump will be, but we do know
445 	 * that we need to reserve space for metadata and that we need two
446 	 * dump headers.  Also leave room for one ustar header and one block
447 	 * of data.
448 	 */
449 	if (di->mediasize < SIZEOF_METADATA + 2 * sizeof(kdh)) {
450 		printf("Insufficient space on dump partition for minimal textdump.\n");
451 		return;
452 	}
453 	textdump_error = 0;
454 
455 	/*
456 	 * Disable EKCD because we don't provide encrypted textdumps.
457 	 */
458 	kdc = di->kdcrypto;
459 	di->kdcrypto = NULL;
460 
461 	/*
462 	 * Position the start of the dump so that we'll write the kernel dump
463 	 * trailer immediately before the end of the partition, and then work
464 	 * our way back.  We will rewrite this header later to reflect the
465 	 * true size if things go well.
466 	 */
467 	textdump_offset = di->mediasize - sizeof(kdh);
468 	textdump_saveoff(&trailer_offset);
469 	dump_init_header(di, &kdh, TEXTDUMPMAGIC, KERNELDUMP_TEXT_VERSION, 0);
470 	(void)textdump_writenextblock(di, (char *)&kdh);
471 
472 	/*
473 	 * Write a series of files in ustar format.
474 	 */
475 	if (textdump_do_ddb)
476 		db_capture_dump(di);
477 #ifdef INCLUDE_CONFIG_FILE
478 	if (textdump_do_config)
479 		textdump_dump_config(di);
480 #endif
481 	if (textdump_do_msgbuf)
482 		textdump_dump_msgbuf(di);
483 	if (textdump_do_panic && KERNEL_PANICKED())
484 		textdump_dump_panic(di);
485 	if (textdump_do_version)
486 		textdump_dump_version(di);
487 
488 	/*
489 	 * Now that we know the true size, we can write out the header, then
490 	 * seek back to the end and rewrite the trailer with the correct
491 	 * size.
492 	 */
493 	dumplen = trailer_offset - (textdump_offset + TEXTDUMP_BLOCKSIZE);
494 	dump_init_header(di, &kdh, TEXTDUMPMAGIC, KERNELDUMP_TEXT_VERSION,
495 	    dumplen);
496 	(void)textdump_writenextblock(di, (char *)&kdh);
497 	textdump_restoreoff(trailer_offset);
498 	(void)textdump_writenextblock(di, (char *)&kdh);
499 
500 	/*
501 	 * Terminate the dump, report any errors, and clear the pending flag.
502 	 */
503 	if (textdump_error == 0)
504 		(void)dump_write(di, NULL, 0, 0);
505 	if (textdump_error == ENOSPC)
506 		printf("Textdump: Insufficient space on dump partition\n");
507 	else if (textdump_error != 0)
508 		printf("Textdump: Error %d writing dump\n", textdump_error);
509 	else
510 		printf("Textdump complete.\n");
511 	textdump_pending = 0;
512 
513 	/*
514 	 * Restore EKCD status.
515 	 */
516 	di->kdcrypto = kdc;
517 }
518 
519 /*-
520  * DDB(4) command to manage textdumps:
521  *
522  * textdump set        - request a textdump
523  * textdump status     - print DDB output textdump status
524  * textdump unset      - clear textdump request
525  */
526 static void
527 db_textdump_usage(void)
528 {
529 
530 	db_printf("textdump [unset|set|status|dump]\n");
531 }
532 
533 void
534 db_textdump_cmd(db_expr_t addr, bool have_addr, db_expr_t count, char *modif)
535 {
536 	int t;
537 
538 	t = db_read_token();
539 	if (t != tIDENT) {
540 		db_textdump_usage();
541 		return;
542 	}
543 	if (db_read_token() != tEOL) {
544 		db_textdump_usage();
545 		return;
546 	}
547 	if (strcmp(db_tok_string, "set") == 0) {
548 		textdump_pending = 1;
549 		db_printf("textdump set\n");
550 	} else if (strcmp(db_tok_string, "status") == 0) {
551 		if (textdump_pending)
552 			db_printf("textdump is set\n");
553 		else
554 			db_printf("textdump is not set\n");
555 	} else if (strcmp(db_tok_string, "unset") == 0) {
556 		textdump_pending = 0;
557 		db_printf("textdump unset\n");
558 	} else if (strcmp(db_tok_string, "dump") == 0) {
559 		textdump_pending = 1;
560 		doadump(true);
561 	} else {
562 		db_textdump_usage();
563 	}
564 }
565