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 file systems with significant
32 corruption, but because of this, catastrophic mode forces the
33 file system 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 file sys‐
60 tem). If you specify the -s option, you must also provide the
61 blocksize of the file system via the -b option. (This option
62 is 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 in‐
94 ode (as opposed to a pathname) in the file system 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 file system 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 file system 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 file system 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 extent tree of the inode filespec. The -n flag will
171 cause dump_extents to only display the interior nodes in the ex‐
172 tent tree. The -l flag will cause dump_extents to only display
173 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 file system 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 file system features in the superblock.
211 After setting or clearing any file system features that were re‐
212 quested, print the current state of the file system 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 file system.
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] [-n num_trans ] [-i filespec] [-f jour‐
323 nal_file] [output_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 to print the contents of all of
336 the descriptor blocks. The -b option causes logdump to print
337 all journal records that refer to the specified block. The -c
338 option will print out the contents of all of the data blocks se‐
339 lected 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 The -n option causes logdump to continue past a journal block
346 which is missing a magic number. Instead, it will stop only
347 when the entire log is printed or after num_trans transactions.
348 ls [-l] [-c] [-d] [-p] [-r] filespec
350 Print a listing of the files in the directory filespec. The -c
351 flag causes directory block checksums (if present) to be dis‐
352 played. The -d flag will list deleted entries in the directory.
353 The -l flag will list files using a more verbose format. The -p
354 flag will list the files in a format which is more easily
355 parsable by scripts, as well as making it more clear when there
356 are spaces or other non-printing characters at the end of file‐
357 names. The -r flag will force the printing of the filename,
358 even if it is encrypted.
359 list_deleted_inodes [limit]
361 List deleted inodes, optionally limited to those deleted within
362 limit seconds ago. Also available as lsdel.
363 This command was useful for recovering from accidental file
365 deletions for ext2 file systems. Unfortunately, it is not use‐
366 ful for this purpose if the files were deleted using ext3 or
367 ext4, since the inode's data blocks are no longer available af‐
368 ter the inode is released.
369 modify_inode filespec
371 Modify the contents of the inode structure in the inode file‐
372 spec. Also available as mi.
373 mkdir filespec
375 Make a directory.
376 mknod filespec [p|[[c|b] major minor]]
378 Create a special device file (a named pipe, character or block
379 device). If a character or block device is to be made, the ma‐
380 jor and minor device numbers must be specified.
381 ncheck [-c] inode_num ...
383 Take the requested list of inode numbers, and print a listing of
384 pathnames to those inodes. The -c flag will enable checking the
385 file type information in the directory entry to make sure it
386 matches the inode's type.
387 open [-weficD] [-b blocksize] [-d image_filename] [-s superblock] [-z
389 undo_file] device
390 Open a file system for editing. The -f flag forces the file
391 system to be opened even if there are some unknown or incompati‐
392 ble file system features which would normally prevent the file
393 system from being opened. The -e flag causes the file system to
394 be opened in exclusive mode. The -b, -c, -d, -i, -s, -w, and -D
395 options behave the same as the command-line options to debugfs.
396 punch filespec start_blk [end_blk]
398 Delete the blocks in the inode ranging from start_blk to
399 end_blk. If end_blk is omitted then this command will function
400 as a truncate command; that is, all of the blocks starting at
401 start_blk through to the end of the file will be deallocated.
402 symlink filespec target
404 Make a symbolic link.
405 pwd Print the current working directory.
407 quit Quit debugfs
409 rdump directory[...] destination
411 Recursively dump directory, or multiple directories, and all its
412 contents (including regular files, symbolic links, and other di‐
413 rectories) into the named destination, which should be an exist‐
414 ing directory on the native file system.
415 rm pathname
417 Unlink pathname. If this causes the inode pointed to by path‐
418 name to have no other references, deallocate the file. This
419 command functions as the unlink() system call.
420 rmdir filespec
422 Remove the directory filespec.
423 setb block [count]
425 Mark the block number block as allocated. If the optional argu‐
426 ment count is present, then count blocks starting at block num‐
427 ber block will be marked as allocated.
428 set_block_group bgnum field value
430 Modify the block group descriptor specified by bgnum so that the
431 block group descriptor field field has value value. Also avail‐
432 able as set_bg.
433 set_current_time time
435 Set current time in seconds since Unix epoch to use when setting
436 file system fields.
437 seti filespec [num]
439 Mark inode filespec as in use in the inode bitmap. If num is
440 specified, also set num-1 inodes after the specified inode.
441 set_inode_field filespec field value
443 Modify the inode specified by filespec so that the inode field
444 field has value value. The list of valid inode fields which can
445 be set via this command can be displayed by using the command:
446 set_inode_field -l Also available as sif.
447 set_mmp_value field value
449 Modify the multiple-mount protection (MMP) data so that the MMP
450 field field has value value. The list of valid MMP fields which
451 can be set via this command can be displayed by using the com‐
452 mand: set_mmp_value -l Also available as smmp.
453 set_super_value field value
455 Set the superblock field field to value. The list of valid su‐
456 perblock fields which can be set via this command can be dis‐
457 played by using the command: set_super_value -l Also available
458 as ssv.
459 show_debugfs_params
461 Display debugfs parameters such as information about currently
462 opened file system.
463 show_super_stats [-h]
465 List the contents of the super block and the block group de‐
466 scriptors. If the -h flag is given, only print out the su‐
467 perblock contents. Also available as stats.
468 stat filespec
470 Display the contents of the inode structure of the inode file‐
471 spec.
472 supported_features
474 Display file system features supported by this version of de‐
475 bugfs.
476 testb block [count]
478 Test if the block number block is marked as allocated in the
479 block bitmap. If the optional argument count is present, then
480 count blocks starting at block number block will be tested.
481 testi filespec
483 Test if the inode filespec is marked as allocated in the inode
484 bitmap.
485 undel <inode_number> [pathname]
487 Undelete the specified inode number (which must be surrounded by
488 angle brackets) so that it and its blocks are marked in use, and
489 optionally link the recovered inode to the specified pathname.
490 The e2fsck command should always be run after using the undel
491 command to recover deleted files.
492 Note that if you are recovering a large number of deleted files,
494 linking the inode to a directory may require the directory to be
495 expanded, which could allocate a block that had been used by one
496 of the yet-to-be-undeleted files. So it is safer to undelete
497 all of the inodes without specifying a destination pathname, and
498 then in a separate pass, use the debugfs link command to link
499 the inode to the destination pathname, or use e2fsck to check
500 the file system and link all of the recovered inodes to the
501 lost+found directory.
502 unlink pathname
504 Remove the link specified by pathname to an inode. Note this
505 does not adjust the inode reference counts.
506 write source_file out_file
508 Copy the contents of source_file into a newly-created file in
509 the file system named out_file.
510 zap_block [-f filespec] [-o offset] [-l length] [-p pattern] block_num
512 Overwrite the block specified by block_num with zero (NUL)
513 bytes, or if -p is given use the byte specified by pattern. If
514 -f is given then block_num is relative to the start of the file
515 given by filespec. The -o and -l options limit the range of
516 bytes to zap to the specified offset and length relative to the
517 start of the block.
518 zap_block [-f filespec] [-b bit] block_num
520 Bit-flip portions of the physical block_num. If -f is given,
521 then block_num is a logical block relative to the start of file‐
522 spec.
523
525 DEBUGFS_PAGER, PAGER
526 The debugfs program always pipes the output of the some commands
527 through a pager program. These commands include: show_su‐
528 per_stats (stats), list_directory (ls), show_inode_info (stat),
529 list_deleted_inodes (lsdel), and htree_dump. The specific pager
530 can explicitly specified by the DEBUGFS_PAGER environment vari‐
531 able, and if it is not set, by the PAGER environment variable.
532 Note that since a pager is always used, the less(1) pager is not
534 particularly appropriate, since it clears the screen before dis‐
535 playing the output of the command and clears the output the
536 screen when the pager is exited. Many users prefer to use the
537 less(1) pager for most purposes, which is why the DEBUGFS_PAGER
538 environment variable is available to override the more general
539 PAGER environment variable.
540
542 debugfs was written by Theodore Ts'o <tytso@mit.edu>.
543
545 dumpe2fs(8), tune2fs(8), e2fsck(8), mke2fs(8), ext4(5)
546E2fsprogs version 1.47.0 February 2023 DEBUGFS(8)