1DEBUGFS(8)                  System Manager's Manual                 DEBUGFS(8)
2
3
4

NAME

6       debugfs - ext2/ext3/ext4 file system debugger
7

SYNOPSIS

9       debugfs  [ -DVwcin ] [ -b blocksize ] [ -s superblock ] [ -f cmd_file ]
10       [ -R request ] [ -d data_source_device ] [ -z undo_file ] [ device ]
11

DESCRIPTION

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
17       device is a block device (e.g., /dev/sdXX) or  a  file  containing  the
18       file system.
19

OPTIONS

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
25       -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
29       -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
35       -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
45       -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
50       -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
56       -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
65       -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
70       -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
74       -R request
75              Causes debugfs to execute the single command request,  and  then
76              exit.
77
78       -V     print the version number of debugfs and exit.
79
80       -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
89              WARNING: The undo file cannot be used to recover from a power or
90              system crash.
91

SPECIFYING FILES

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

COMMANDS

105       This is a list of the commands which debugfs supports.
106
107       blocks filespec
108              Print the blocks used by the inode filespec to stdout.
109
110       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
115       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
123       cat filespec
124              Dump the contents of the inode filespec to stdout.
125
126       cd filespec
127              Change the current working directory to filespec.
128
129       chroot filespec
130              Change the root directory to be the directory filespec.
131
132       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
138       clri filespec
139              Clear the contents of the inode filespec.
140
141       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
145       dirsearch filespec filename
146              Search the directory filespec for filename.
147
148       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
153       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
158       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
164       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
169       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
175              (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
181       dump_unused
182              Dump unused blocks which contain non-null bytes.
183
184       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
188       ea_list filespec
189              List  the  extended attributes associated with the file filespec
190              to standard output.
191
192       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
196       ea_rm filespec attr_names...
197              Remove the extended attribute attr_name from the file filespec.
198
199       expand_dir filespec
200              Expand the directory filespec.
201
202       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
209       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
214       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
222       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
226       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
234       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
239       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
246       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
250       get_quota quota_type id
251              Display  quota information for given quota type (user, group, or
252              project) and ID.
253
254       help   Print a list of commands understood by debugfs.
255
256       htree_dump filespec
257              Dump the  hash-indexed  directory  filespec,  showing  its  tree
258              structure.
259
260       icheck block ...
261              Print  a  listing of the inodes which use the one or more blocks
262              specified on the command line.
263
264       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
274       imap filespec
275              Print the location of the inode data structure (in the inode ta‐
276              ble) of the inode filespec.
277
278       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
285       journal_close
286              Close the open journal.
287
288       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
294       journal_run
295              Replay all transactions in the open journal.
296
297       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
305       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
310       lcd directory
311              Change the current working directory of the debugfs  process  to
312              directory on the native file system.
313
314       list_quota quota_type
315              Display  quota information for given quota type (user, group, or
316              project).
317
318       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
322       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
332              The -S option causes logdump to print the contents of the  jour‐
333              nal superblock.
334
335              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
341              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
345       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
356       list_deleted_inodes [limit]
357              List  deleted inodes, optionally limited to those deleted within
358              limit seconds ago.  Also available as lsdel.
359
360              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
366       modify_inode filespec
367              Modify the contents of the inode structure in  the  inode  file‐
368              spec.  Also available as mi.
369
370       mkdir filespec
371              Make a directory.
372
373       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
378       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
384       open [-weficD] [-b blocksize] [-d image_filename] [-s  superblock]  [-z
385       undo_file] device
386              Open  a  file  system  for editing.  The -f flag forces the file
387              system to be opened even if there are some unknown or incompati‐
388              ble  file  system features which would normally prevent the file
389              system from being opened.  The -e flag causes the file system to
390              be 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
393       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
399       symlink filespec target
400              Make a symbolic link.
401
402       pwd    Print the current working directory.
403
404       quit   Quit debugfs
405
406       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 file system.
411
412       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
417       rmdir filespec
418              Remove the directory filespec.
419
420       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
425       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
430       set_current_time time
431              Set current time in seconds since Unix epoch to use when setting
432              file system fields.
433
434       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
438       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
444       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
450       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
456       show_debugfs_params
457              Display  debugfs  parameters such as information about currently
458              opened file system.
459
460       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
465       stat filespec
466              Display the contents of the inode structure of the  inode  file‐
467              spec.
468
469       supported_features
470              Display  file  system  features supported by this version of de‐
471              bugfs.
472
473       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
478       testi filespec
479              Test if the inode filespec is marked as allocated in  the  inode
480              bitmap.
481
482       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
489              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 file system and link all of  the  recovered  inodes  to  the
497              lost+found directory.
498
499       unlink pathname
500              Remove  the  link  specified by pathname to an inode.  Note this
501              does not adjust the inode reference counts.
502
503       write source_file out_file
504              Copy the contents of source_file into a  newly-created  file  in
505              the file system named out_file.
506
507       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
515       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

ENVIRONMENT VARIABLES

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
529              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

AUTHOR

538       debugfs was written by Theodore Ts'o <tytso@mit.edu>.
539

SEE ALSO

541       dumpe2fs(8), tune2fs(8), e2fsck(8), mke2fs(8), ext4(5)
542
543
544
545E2fsprogs version 1.46.5         December 2021                      DEBUGFS(8)
Impressum