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
63 extremely 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
94 inode (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.
211 After setting or clearing any filesystem features that were
212 requested, print the current state of the filesystem feature
213 set.
214 filefrag [-dvr] filespec
216 Print the number of contiguous extents in filespec. If filespec
217 is a directory and the -d option is not specified, filefrag will
218 print the number of contiguous extents for each file in the
219 directory. The -v option will cause filefrag print a tabular
220 listing of the contiguous extents in the file. The -r option
221 will cause filefrag to do a recursive listing of the directory.
222 find_free_block [count [goal]]
224 Find the first count free blocks, starting from goal and allo‐
225 cate it. Also available as ffb.
226 find_free_inode [dir [mode]]
228 Find a free inode and allocate it. If present, dir specifies
229 the inode number of the directory which the inode is to be
230 located. The second optional argument mode specifies the per‐
231 missions of the new inode. (If the directory bit is set on the
232 mode, the allocation routine will function differently.) Also
233 available as ffi.
234 freeb block [count]
236 Mark the block number block as not allocated. If the optional
237 argument count is present, then count blocks starting at block
238 number block will be marked as not allocated.
239 freefrag [-c chunk_kb]
241 Report free space fragmentation on the currently open file sys‐
242 tem. If the -c option is specified then the filefrag command
243 will print how many free chunks of size chunk_kb can be found in
244 the file system. The chunk size must be a power of two and be
245 larger than the file system block size.
246 freei filespec [num]
248 Free the inode specified by filespec. If num is specified, also
249 clear num-1 inodes after the specified inode.
250 get_quota quota_type id
252 Display quota information for given quota type (user, group, or
253 project) and ID.
254 help Print a list of commands understood by debugfs.
256 htree_dump filespec
258 Dump the hash-indexed directory filespec, showing its tree
259 structure.
260 icheck block ...
262 Print a listing of the inodes which use the one or more blocks
263 specified on the command line.
264 inode_dump [-b]|[-e]|[-x] filespec
266 Print the contents of the inode data structure in hex and ASCII
267 format. The -b option causes the command to only dump the con‐
268 tents of the i_blocks array. The -e option causes the command
269 to only dump the contents of the extra inode space, which is
270 used to store in-line extended attributes. The -x option causes
271 the command to dump the extra inode space interpreted and
272 extended attributes. This is useful to debug corrupted inodes
273 containing extended attributes.
274 imap filespec
276 Print the location of the inode data structure (in the inode ta‐
277 ble) of the inode filespec.
278 init_filesys device blocksize
280 Create an ext2 file system on device with device size blocksize.
281 Note that this does not fully initialize all of the data struc‐
282 tures; to do this, use the mke2fs(8) program. This is just a
283 call to the low-level library, which sets up the superblock and
284 block descriptors.
285 journal_close
287 Close the open journal.
288 journal_open [-c] [-v ver] [-f ext_jnl]
290 Opens the journal for reading and writing. Journal checksumming
291 can be enabled by supplying -c; checksum formats 2 and 3 can be
292 selected with the -v option. An external journal can be loaded
293 from ext_jnl.
294 journal_run
296 Replay all transactions in the open journal.
297 journal_write [-b blocks] [-r revoke] [-c] file
299 Write a transaction to the open journal. The list of blocks to
300 write should be supplied as a comma-separated list in blocks;
301 the blocks themselves should be readable from file. A list of
302 blocks to revoke can be supplied as a comma-separated list in
303 revoke. By default, a commit record is written at the end; the
304 -c switch writes an uncommitted transaction.
305 kill_file filespec
307 Deallocate the inode filespec and its blocks. Note that this
308 does not remove any directory entries (if any) to this inode.
309 See the rm(1) command if you wish to unlink a file.
310 lcd directory
312 Change the current working directory of the debugfs process to
313 directory on the native filesystem.
314 list_quota quota_type
316 Display quota information for given quota type (user, group, or
317 project).
318 ln filespec dest_file
320 Create a link named dest_file which is a hard link to filespec.
321 Note this does not adjust the inode reference counts.
322 logdump [-acsOS] [-b block] [-i filespec] [-f journal_file] [out‐
324 put_file]
325 Dump the contents of the ext3 journal. By default, dump the
326 journal inode as specified in the superblock. However, this can
327 be overridden with the -i option, which dumps the journal from
328 the internal inode given by filespec. A regular file containing
329 journal data can be specified using the -f option. Finally, the
330 -s option utilizes the backup information in the superblock to
331 locate the journal.
332 The -S option causes logdump to print the contents of the jour‐
334 nal superblock.
335 The -a option causes the logdump program to print the contents
337 of all of the descriptor blocks. The -b option causes logdump
338 to print all journal records that refer to the specified block.
339 The -c option will print out the contents of all of the data
340 blocks selected by the -a and -b options.
341 The -O option causes logdump to display old (checkpointed) jour‐
343 nal entries. This can be used to try to track down journal
344 problems even after the journal has been replayed.
345 ls [-l] [-c] [-d] [-p] [-r] filespec
347 Print a listing of the files in the directory filespec. The -c
348 flag causes directory block checksums (if present) to be dis‐
349 played. The -d flag will list deleted entries in the directory.
350 The -l flag will list files using a more verbose format. The -p
351 flag will list the files in a format which is more easily
352 parsable by scripts, as well as making it more clear when there
353 are spaces or other non-printing characters at the end of file‐
354 names. The -r flag will force the printing of the filename,
355 even if it is encrypted.
356 list_deleted_inodes [limit]
358 List deleted inodes, optionally limited to those deleted within
359 limit seconds ago. Also available as lsdel.
360 This command was useful for recovering from accidental file
362 deletions for ext2 file systems. Unfortunately, it is not use‐
363 ful for this purpose if the files were deleted using ext3 or
364 ext4, since the inode's data blocks are no longer available
365 after the inode is released.
366 modify_inode filespec
368 Modify the contents of the inode structure in the inode file‐
369 spec. Also available as mi.
370 mkdir filespec
372 Make a directory.
373 mknod filespec [p|[[c|b] major minor]]
375 Create a special device file (a named pipe, character or block
376 device). If a character or block device is to be made, the
377 major and minor device numbers must be specified.
378 ncheck [-c] inode_num ...
380 Take the requested list of inode numbers, and print a listing of
381 pathnames to those inodes. The -c flag will enable checking the
382 file type information in the directory entry to make sure it
383 matches the inode's type.
384 open [-weficD] [-b blocksize] [-d image_filename] [-s superblock] [-z
386 undo_file] device
387 Open a filesystem for editing. The -f flag forces the filesys‐
388 tem to be opened even if there are some unknown or incompatible
389 filesystem features which would normally prevent the filesystem
390 from being opened. The -e flag causes the filesystem to be
391 opened in exclusive mode. The -b, -c, -d, -i, -s, -w, and -D
392 options behave the same as the command-line options to debugfs.
393 punch filespec start_blk [end_blk]
395 Delete the blocks in the inode ranging from start_blk to
396 end_blk. If end_blk is omitted then this command will function
397 as a truncate command; that is, all of the blocks starting at
398 start_blk through to the end of the file will be deallocated.
399 symlink filespec target
401 Make a symbolic link.
402 pwd Print the current working directory.
404 quit Quit debugfs
406 rdump directory[...] destination
408 Recursively dump directory, or multiple directories, and all its
409 contents (including regular files, symbolic links, and other
410 directories) into the named destination, which should be an
411 existing directory on the native filesystem.
412 rm pathname
414 Unlink pathname. If this causes the inode pointed to by path‐
415 name to have no other references, deallocate the file. This
416 command functions as the unlink() system call.
417 rmdir filespec
419 Remove the directory filespec.
420 setb block [count]
422 Mark the block number block as allocated. If the optional argu‐
423 ment count is present, then count blocks starting at block num‐
424 ber block will be marked as allocated.
425 set_block_group bgnum field value
427 Modify the block group descriptor specified by bgnum so that the
428 block group descriptor field field has value value. Also avail‐
429 able as set_bg.
430 set_current_time time
432 Set current time in seconds since Unix epoch to use when setting
433 filesystem fields.
434 seti filespec [num]
436 Mark inode filespec as in use in the inode bitmap. If num is
437 specified, also set num-1 inodes after the specified inode.
438 set_inode_field filespec field value
440 Modify the inode specified by filespec so that the inode field
441 field has value value. The list of valid inode fields which can
442 be set via this command can be displayed by using the command:
443 set_inode_field -l Also available as sif.
444 set_mmp_value field value
446 Modify the multiple-mount protection (MMP) data so that the MMP
447 field field has value value. The list of valid MMP fields which
448 can be set via this command can be displayed by using the com‐
449 mand: set_mmp_value -l Also available as smmp.
450 set_super_value field value
452 Set the superblock field field to value. The list of valid
453 superblock fields which can be set via this command can be dis‐
454 played by using the command: set_super_value -l Also available
455 as ssv.
456 show_debugfs_params
458 Display debugfs parameters such as information about currently
459 opened filesystem.
460 show_super_stats [-h]
462 List the contents of the super block and the block group
463 descriptors. If the -h flag is given, only print out the
464 superblock contents. Also available as stats.
465 stat filespec
467 Display the contents of the inode structure of the inode file‐
468 spec.
469 supported_features
471 Display filesystem features supported by this version of
472 debugfs.
473 testb block [count]
475 Test if the block number block is marked as allocated in the
476 block bitmap. If the optional argument count is present, then
477 count blocks starting at block number block will be tested.
478 testi filespec
480 Test if the inode filespec is marked as allocated in the inode
481 bitmap.
482 undel <inode_number> [pathname]
484 Undelete the specified inode number (which must be surrounded by
485 angle brackets) so that it and its blocks are marked in use, and
486 optionally link the recovered inode to the specified pathname.
487 The e2fsck command should always be run after using the undel
488 command to recover deleted files.
489 Note that if you are recovering a large number of deleted files,
491 linking the inode to a directory may require the directory to be
492 expanded, which could allocate a block that had been used by one
493 of the yet-to-be-undeleted files. So it is safer to undelete
494 all of the inodes without specifying a destination pathname, and
495 then in a separate pass, use the debugfs link command to link
496 the inode to the destination pathname, or use e2fsck to check
497 the filesystem and link all of the recovered inodes to the
498 lost+found directory.
499 unlink pathname
501 Remove the link specified by pathname to an inode. Note this
502 does not adjust the inode reference counts.
503 write source_file out_file
505 Copy the contents of source_file into a newly-created file in
506 the filesystem named out_file.
507 zap_block [-f filespec] [-o offset] [-l length] [-p pattern] block_num
509 Overwrite the block specified by block_num with zero (NUL)
510 bytes, or if -p is given use the byte specified by pattern. If
511 -f is given then block_num is relative to the start of the file
512 given by filespec. The -o and -l options limit the range of
513 bytes to zap to the specified offset and length relative to the
514 start of the block.
515 zap_block [-f filespec] [-b bit] block_num
517 Bit-flip portions of the physical block_num. If -f is given,
518 then block_num is a logical block relative to the start of file‐
519 spec.
520
522 DEBUGFS_PAGER, PAGER
523 The debugfs program always pipes the output of the some commands
524 through a pager program. These commands include:
525 show_super_stats (stats), list_directory (ls), show_inode_info
526 (stat), list_deleted_inodes (lsdel), and htree_dump. The spe‐
527 cific pager can explicitly specified by the DEBUGFS_PAGER envi‐
528 ronment variable, and if it is not set, by the PAGER environment
529 variable.
530 Note that since a pager is always used, the less(1) pager is not
532 particularly appropriate, since it clears the screen before dis‐
533 playing the output of the command and clears the output the
534 screen when the pager is exited. Many users prefer to use the
535 less(1) pager for most purposes, which is why the DEBUGFS_PAGER
536 environment variable is available to override the more general
537 PAGER environment variable.
538
540 debugfs was written by Theodore Ts'o <tytso@mit.edu>.
541
543 dumpe2fs(8), tune2fs(8), e2fsck(8), mke2fs(8), ext4(5)
544E2fsprogs version 1.45.3 July 2019 DEBUGFS(8)