1DEBUGFS(8) System Manager's Manual DEBUGFS(8)
2
6 debugfs - ext2/ext3/ext4 file system debugger
7
9 debugfs [ -DVwcin ] [ -b blocksize ] [ -s superblock ] [ -f cmd_file ]
10 [ -R request ] [ -d data_source_device ] [ -z undo_file ] [ device ]
11
13 The debugfs program is an interactive file system debugger. It can be
14 used to examine and change the state of an ext2, ext3, or ext4 file
15 system.
16 device is a block device (e.g., /dev/sdXX) or a file containing the
18 file system.
19
21 -w Specifies that the file system should be opened in read-write
22 mode. Without this option, the file system is opened in read-
23 only mode.
24 -n Disables metadata checksum verification. This should only be
26 used if you believe the metadata to be correct despite the com‐
27 plaints of e2fsprogs.
28 -c Specifies that the file system should be opened in catastrophic
30 mode, in which the inode and group bitmaps are not read ini‐
31 tially. This can be useful for filesystems with significant
32 corruption, but because of this, catastrophic mode forces the
33 filesystem to be opened read-only.
34 -i Specifies that device represents an ext2 image file created by
36 the e2image program. Since the ext2 image file only contains
37 the superblock, block group descriptor, block and inode alloca‐
38 tion bitmaps, and the inode table, many debugfs commands will
39 not function properly. Warning: no safety checks are in place,
40 and debugfs may fail in interesting ways if commands such as ls,
41 dump, etc. are tried without specifying the data_source_device
42 using the -d option. debugfs is a debugging tool. It has rough
43 edges!
44 -d data_source_device
46 Used with the -i option, specifies that data_source_device
47 should be used when reading blocks not found in the ext2 image
48 file. This includes data, directory, and indirect blocks.
49 -b blocksize
51 Forces the use of the given block size (in bytes) for the file
52 system, rather than detecting the correct block size automati‐
53 cally. (This option is rarely needed; it is used primarily when
54 the file system is extremely badly damaged/corrupted.)
55 -s superblock
57 Causes the file system superblock to be read from the given
58 block number, instead of using the primary superblock (located
59 at an offset of 1024 bytes from the beginning of the filesys‐
60 tem). If you specify the -s option, you must also provide the
61 blocksize of the filesystem via the -b option. (This option is
62 rarely needed; it is used primarily when the file system is ex‐
63 tremely badly damaged/corrupted.)
64 -f cmd_file
66 Causes debugfs to read in commands from cmd_file, and execute
67 them. When debugfs is finished executing those commands, it
68 will exit.
69 -D Causes debugfs to open the device using Direct I/O, bypassing
71 the buffer cache. Note that some Linux devices, notably device
72 mapper as of this writing, do not support Direct I/O.
73 -R request
75 Causes debugfs to execute the single command request, and then
76 exit.
77 -V print the version number of debugfs and exit.
79 -z undo_file
81 Before overwriting a file system block, write the old contents
82 of the block to an undo file. This undo file can be used with
83 e2undo(8) to restore the old contents of the file system should
84 something go wrong. If the empty string is passed as the
85 undo_file argument, the undo file will be written to a file
86 named debugfs-device.e2undo in the directory specified via the
87 E2FSPROGS_UNDO_DIR environment variable.
88 WARNING: The undo file cannot be used to recover from a power or
90 system crash.
91
93 Many debugfs commands take a filespec as an argument to specify an in‐
94 ode (as opposed to a pathname) in the filesystem which is currently
95 opened by debugfs. The filespec argument may be specified in two
96 forms. The first form is an inode number surrounded by angle brackets,
97 e.g., <2>. The second form is a pathname; if the pathname is prefixed
98 by a forward slash ('/'), then it is interpreted relative to the root
99 of the filesystem which is currently opened by debugfs. If not, the
100 pathname is interpreted relative to the current working directory as
101 maintained by debugfs. This may be modified by using the debugfs com‐
102 mand cd.
103
105 This is a list of the commands which debugfs supports.
106 blocks filespec
108 Print the blocks used by the inode filespec to stdout.
109 bmap [ -a ] filespec logical_block [physical_block]
111 Print or set the physical block number corresponding to the log‐
112 ical block number logical_block in the inode filespec. If the
113 -a flag is specified, try to allocate a block if necessary.
114 block_dump '[ -x ] [-f filespec] block_num
116 Dump the filesystem block given by block_num in hex and ASCII
117 format to the console. If the -f option is specified, the block
118 number is relative to the start of the given filespec. If the
119 -x option is specified, the block is interpreted as an extended
120 attribute block and printed to show the structure of extended
121 attribute data structures.
122 cat filespec
124 Dump the contents of the inode filespec to stdout.
125 cd filespec
127 Change the current working directory to filespec.
128 chroot filespec
130 Change the root directory to be the directory filespec.
131 close [-a]
133 Close the currently open file system. If the -a option is spec‐
134 ified, write out any changes to the superblock and block group
135 descriptors to all of the backup superblocks, not just to the
136 master superblock.
137 clri filespec
139 Clear the contents of the inode filespec.
140 copy_inode source_inode destination_inode
142 Copy the contents of the inode structure in source_inode and use
143 it to overwrite the inode structure at destination_inode.
144 dirsearch filespec filename
146 Search the directory filespec for filename.
147 dirty [-clean]
149 Mark the filesystem as dirty, so that the superblocks will be
150 written on exit. Additionally, clear the superblock's valid
151 flag, or set it if -clean is specified.
152 dump [-p] filespec out_file
154 Dump the contents of the inode filespec to the output file
155 out_file. If the -p option is given set the owner, group and
156 permissions information on out_file to match filespec.
157 dump_mmp [mmp_block]
159 Display the multiple-mount protection (mmp) field values. If
160 mmp_block is specified then verify and dump the MMP values from
161 the given block number, otherwise use the s_mmp_block field in
162 the superblock to locate and use the existing MMP block.
163 dx_hash [-h hash_alg] [-s hash_seed] filename
165 Calculate the directory hash of filename. The hash algorithm
166 specified with -h may be legacy, half_md4, or tea. The hash
167 seed specified with -s must be in UUID format.
168 dump_extents [-n] [-l] filespec
170 Dump the the extent tree of the inode filespec. The -n flag
171 will cause dump_extents to only display the interior nodes in
172 the extent tree. The -l flag will cause dump_extents to only
173 display the leaf nodes in the extent tree.
174 (Please note that the length and range of blocks for the last
176 extent in an interior node is an estimate by the extents library
177 functions, and is not stored in filesystem data structures.
178 Hence, the values displayed may not necessarily by accurate and
179 does not indicate a problem or corruption in the file system.)
180 dump_unused
182 Dump unused blocks which contain non-null bytes.
183 ea_get [-f outfile]|[-xVC] [-r] filespec attr_name
185 Retrieve the value of the extended attribute attr_name in the
186 file filespec and write it either to stdout or to outfile.
187 ea_list filespec
189 List the extended attributes associated with the file filespec
190 to standard output.
191 ea_set [-f infile] [-r] filespec attr_name attr_value
193 Set the value of the extended attribute attr_name in the file
194 filespec to the string value attr_value or read it from infile.
195 ea_rm filespec attr_names...
197 Remove the extended attribute attr_name from the file filespec.
198 expand_dir filespec
200 Expand the directory filespec.
201 fallocate filespec start_block [end_block]
203 Allocate and map uninitialized blocks into filespec between log‐
204 ical block start_block and end_block, inclusive. If end_block
205 is not supplied, this function maps until it runs out of free
206 disk blocks or the maximum file size is reached. Existing map‐
207 pings are left alone.
208 feature [fs_feature] [-fs_feature] ...
210 Set or clear various filesystem features in the superblock. Af‐
211 ter setting or clearing any filesystem features that were re‐
212 quested, print the current state of the filesystem feature set.
213 filefrag [-dvr] filespec
215 Print the number of contiguous extents in filespec. If filespec
216 is a directory and the -d option is not specified, filefrag will
217 print the number of contiguous extents for each file in the di‐
218 rectory. The -v option will cause filefrag print a tabular
219 listing of the contiguous extents in the file. The -r option
220 will cause filefrag to do a recursive listing of the directory.
221 find_free_block [count [goal]]
223 Find the first count free blocks, starting from goal and allo‐
224 cate it. Also available as ffb.
225 find_free_inode [dir [mode]]
227 Find a free inode and allocate it. If present, dir specifies
228 the inode number of the directory which the inode is to be lo‐
229 cated. The second optional argument mode specifies the permis‐
230 sions of the new inode. (If the directory bit is set on the
231 mode, the allocation routine will function differently.) Also
232 available as ffi.
233 freeb block [count]
235 Mark the block number block as not allocated. If the optional
236 argument count is present, then count blocks starting at block
237 number block will be marked as not allocated.
238 freefrag [-c chunk_kb]
240 Report free space fragmentation on the currently open file sys‐
241 tem. If the -c option is specified then the filefrag command
242 will print how many free chunks of size chunk_kb can be found in
243 the file system. The chunk size must be a power of two and be
244 larger than the file system block size.
245 freei filespec [num]
247 Free the inode specified by filespec. If num is specified, also
248 clear num-1 inodes after the specified inode.
249 get_quota quota_type id
251 Display quota information for given quota type (user, group, or
252 project) and ID.
253 help Print a list of commands understood by debugfs.
255 htree_dump filespec
257 Dump the hash-indexed directory filespec, showing its tree
258 structure.
259 icheck block ...
261 Print a listing of the inodes which use the one or more blocks
262 specified on the command line.
263 inode_dump [-b]|[-e]|[-x] filespec
265 Print the contents of the inode data structure in hex and ASCII
266 format. The -b option causes the command to only dump the con‐
267 tents of the i_blocks array. The -e option causes the command
268 to only dump the contents of the extra inode space, which is
269 used to store in-line extended attributes. The -x option causes
270 the command to dump the extra inode space interpreted and ex‐
271 tended attributes. This is useful to debug corrupted inodes
272 containing extended attributes.
273 imap filespec
275 Print the location of the inode data structure (in the inode ta‐
276 ble) of the inode filespec.
277 init_filesys device blocksize
279 Create an ext2 file system on device with device size blocksize.
280 Note that this does not fully initialize all of the data struc‐
281 tures; to do this, use the mke2fs(8) program. This is just a
282 call to the low-level library, which sets up the superblock and
283 block descriptors.
284 journal_close
286 Close the open journal.
287 journal_open [-c] [-v ver] [-f ext_jnl]
289 Opens the journal for reading and writing. Journal checksumming
290 can be enabled by supplying -c; checksum formats 2 and 3 can be
291 selected with the -v option. An external journal can be loaded
292 from ext_jnl.
293 journal_run
295 Replay all transactions in the open journal.
296 journal_write [-b blocks] [-r revoke] [-c] file
298 Write a transaction to the open journal. The list of blocks to
299 write should be supplied as a comma-separated list in blocks;
300 the blocks themselves should be readable from file. A list of
301 blocks to revoke can be supplied as a comma-separated list in
302 revoke. By default, a commit record is written at the end; the
303 -c switch writes an uncommitted transaction.
304 kill_file filespec
306 Deallocate the inode filespec and its blocks. Note that this
307 does not remove any directory entries (if any) to this inode.
308 See the rm(1) command if you wish to unlink a file.
309 lcd directory
311 Change the current working directory of the debugfs process to
312 directory on the native filesystem.
313 list_quota quota_type
315 Display quota information for given quota type (user, group, or
316 project).
317 ln filespec dest_file
319 Create a link named dest_file which is a hard link to filespec.
320 Note this does not adjust the inode reference counts.
321 logdump [-acsOS] [-b block] [-i filespec] [-f journal_file] [out‐
323 put_file]
324 Dump the contents of the ext3 journal. By default, dump the
325 journal inode as specified in the superblock. However, this can
326 be overridden with the -i option, which dumps the journal from
327 the internal inode given by filespec. A regular file containing
328 journal data can be specified using the -f option. Finally, the
329 -s option utilizes the backup information in the superblock to
330 locate the journal.
331 The -S option causes logdump to print the contents of the jour‐
333 nal superblock.
334 The -a option causes the logdump program to print the contents
336 of all of the descriptor blocks. The -b option causes logdump
337 to print all journal records that refer to the specified block.
338 The -c option will print out the contents of all of the data
339 blocks selected by the -a and -b options.
340 The -O option causes logdump to display old (checkpointed) jour‐
342 nal entries. This can be used to try to track down journal
343 problems even after the journal has been replayed.
344 ls [-l] [-c] [-d] [-p] [-r] filespec
346 Print a listing of the files in the directory filespec. The -c
347 flag causes directory block checksums (if present) to be dis‐
348 played. The -d flag will list deleted entries in the directory.
349 The -l flag will list files using a more verbose format. The -p
350 flag will list the files in a format which is more easily
351 parsable by scripts, as well as making it more clear when there
352 are spaces or other non-printing characters at the end of file‐
353 names. The -r flag will force the printing of the filename,
354 even if it is encrypted.
355 list_deleted_inodes [limit]
357 List deleted inodes, optionally limited to those deleted within
358 limit seconds ago. Also available as lsdel.
359 This command was useful for recovering from accidental file
361 deletions for ext2 file systems. Unfortunately, it is not use‐
362 ful for this purpose if the files were deleted using ext3 or
363 ext4, since the inode's data blocks are no longer available af‐
364 ter the inode is released.
365 modify_inode filespec
367 Modify the contents of the inode structure in the inode file‐
368 spec. Also available as mi.
369 mkdir filespec
371 Make a directory.
372 mknod filespec [p|[[c|b] major minor]]
374 Create a special device file (a named pipe, character or block
375 device). If a character or block device is to be made, the ma‐
376 jor and minor device numbers must be specified.
377 ncheck [-c] inode_num ...
379 Take the requested list of inode numbers, and print a listing of
380 pathnames to those inodes. The -c flag will enable checking the
381 file type information in the directory entry to make sure it
382 matches the inode's type.
383 open [-weficD] [-b blocksize] [-d image_filename] [-s superblock] [-z
385 undo_file] device
386 Open a filesystem for editing. The -f flag forces the filesys‐
387 tem to be opened even if there are some unknown or incompatible
388 filesystem features which would normally prevent the filesystem
389 from being opened. The -e flag causes the filesystem to be
390 opened in exclusive mode. The -b, -c, -d, -i, -s, -w, and -D
391 options behave the same as the command-line options to debugfs.
392 punch filespec start_blk [end_blk]
394 Delete the blocks in the inode ranging from start_blk to
395 end_blk. If end_blk is omitted then this command will function
396 as a truncate command; that is, all of the blocks starting at
397 start_blk through to the end of the file will be deallocated.
398 symlink filespec target
400 Make a symbolic link.
401 pwd Print the current working directory.
403 quit Quit debugfs
405 rdump directory[...] destination
407 Recursively dump directory, or multiple directories, and all its
408 contents (including regular files, symbolic links, and other di‐
409 rectories) into the named destination, which should be an exist‐
410 ing directory on the native filesystem.
411 rm pathname
413 Unlink pathname. If this causes the inode pointed to by path‐
414 name to have no other references, deallocate the file. This
415 command functions as the unlink() system call.
416 rmdir filespec
418 Remove the directory filespec.
419 setb block [count]
421 Mark the block number block as allocated. If the optional argu‐
422 ment count is present, then count blocks starting at block num‐
423 ber block will be marked as allocated.
424 set_block_group bgnum field value
426 Modify the block group descriptor specified by bgnum so that the
427 block group descriptor field field has value value. Also avail‐
428 able as set_bg.
429 set_current_time time
431 Set current time in seconds since Unix epoch to use when setting
432 filesystem fields.
433 seti filespec [num]
435 Mark inode filespec as in use in the inode bitmap. If num is
436 specified, also set num-1 inodes after the specified inode.
437 set_inode_field filespec field value
439 Modify the inode specified by filespec so that the inode field
440 field has value value. The list of valid inode fields which can
441 be set via this command can be displayed by using the command:
442 set_inode_field -l Also available as sif.
443 set_mmp_value field value
445 Modify the multiple-mount protection (MMP) data so that the MMP
446 field field has value value. The list of valid MMP fields which
447 can be set via this command can be displayed by using the com‐
448 mand: set_mmp_value -l Also available as smmp.
449 set_super_value field value
451 Set the superblock field field to value. The list of valid su‐
452 perblock fields which can be set via this command can be dis‐
453 played by using the command: set_super_value -l Also available
454 as ssv.
455 show_debugfs_params
457 Display debugfs parameters such as information about currently
458 opened filesystem.
459 show_super_stats [-h]
461 List the contents of the super block and the block group de‐
462 scriptors. If the -h flag is given, only print out the su‐
463 perblock contents. Also available as stats.
464 stat filespec
466 Display the contents of the inode structure of the inode file‐
467 spec.
468 supported_features
470 Display filesystem features supported by this version of de‐
471 bugfs.
472 testb block [count]
474 Test if the block number block is marked as allocated in the
475 block bitmap. If the optional argument count is present, then
476 count blocks starting at block number block will be tested.
477 testi filespec
479 Test if the inode filespec is marked as allocated in the inode
480 bitmap.
481 undel <inode_number> [pathname]
483 Undelete the specified inode number (which must be surrounded by
484 angle brackets) so that it and its blocks are marked in use, and
485 optionally link the recovered inode to the specified pathname.
486 The e2fsck command should always be run after using the undel
487 command to recover deleted files.
488 Note that if you are recovering a large number of deleted files,
490 linking the inode to a directory may require the directory to be
491 expanded, which could allocate a block that had been used by one
492 of the yet-to-be-undeleted files. So it is safer to undelete
493 all of the inodes without specifying a destination pathname, and
494 then in a separate pass, use the debugfs link command to link
495 the inode to the destination pathname, or use e2fsck to check
496 the filesystem and link all of the recovered inodes to the
497 lost+found directory.
498 unlink pathname
500 Remove the link specified by pathname to an inode. Note this
501 does not adjust the inode reference counts.
502 write source_file out_file
504 Copy the contents of source_file into a newly-created file in
505 the filesystem named out_file.
506 zap_block [-f filespec] [-o offset] [-l length] [-p pattern] block_num
508 Overwrite the block specified by block_num with zero (NUL)
509 bytes, or if -p is given use the byte specified by pattern. If
510 -f is given then block_num is relative to the start of the file
511 given by filespec. The -o and -l options limit the range of
512 bytes to zap to the specified offset and length relative to the
513 start of the block.
514 zap_block [-f filespec] [-b bit] block_num
516 Bit-flip portions of the physical block_num. If -f is given,
517 then block_num is a logical block relative to the start of file‐
518 spec.
519
521 DEBUGFS_PAGER, PAGER
522 The debugfs program always pipes the output of the some commands
523 through a pager program. These commands include: show_su‐
524 per_stats (stats), list_directory (ls), show_inode_info (stat),
525 list_deleted_inodes (lsdel), and htree_dump. The specific pager
526 can explicitly specified by the DEBUGFS_PAGER environment vari‐
527 able, and if it is not set, by the PAGER environment variable.
528 Note that since a pager is always used, the less(1) pager is not
530 particularly appropriate, since it clears the screen before dis‐
531 playing the output of the command and clears the output the
532 screen when the pager is exited. Many users prefer to use the
533 less(1) pager for most purposes, which is why the DEBUGFS_PAGER
534 environment variable is available to override the more general
535 PAGER environment variable.
536
538 debugfs was written by Theodore Ts'o <tytso@mit.edu>.
539
541 dumpe2fs(8), tune2fs(8), e2fsck(8), mke2fs(8), ext4(5)
542E2fsprogs version 1.46.3 July 2021 DEBUGFS(8)