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 filesystems with significant
32              corruption, but because of this, catastrophic  mode  forces  the
33              filesystem 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  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
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
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

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  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
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 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
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  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
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  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
215       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
223       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
227       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
235       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
240       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
247       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
251       get_quota quota_type id
252              Display quota information for given quota type (user, group,  or
253              project) and ID.
254
255       help   Print a list of commands understood by debugfs.
256
257       htree_dump filespec
258              Dump  the  hash-indexed  directory  filespec,  showing  its tree
259              structure.
260
261       icheck block ...
262              Print a listing of the inodes which use the one or  more  blocks
263              specified on the command line.
264
265       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
275       imap filespec
276              Print the location of the inode data structure (in the inode ta‐
277              ble) of the inode filespec.
278
279       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
286       journal_close
287              Close the open journal.
288
289       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
295       journal_run
296              Replay all transactions in the open journal.
297
298       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
306       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
311       lcd directory
312              Change  the  current working directory of the debugfs process to
313              directory on the native filesystem.
314
315       list_quota quota_type
316              Display quota information for given quota type (user, group,  or
317              project).
318
319       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
323       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
333              The  -S option causes logdump to print the contents of the jour‐
334              nal superblock.
335
336              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
342              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
346       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
357       list_deleted_inodes [limit]
358              List deleted inodes, optionally limited to those deleted  within
359              limit seconds ago.  Also available as lsdel.
360
361              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
367       modify_inode filespec
368              Modify  the  contents  of the inode structure in the inode file‐
369              spec.  Also available as mi.
370
371       mkdir filespec
372              Make a directory.
373
374       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
379       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
385       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
394       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
400       symlink filespec target
401              Make a symbolic link.
402
403       pwd    Print the current working directory.
404
405       quit   Quit debugfs
406
407       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
413       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
418       rmdir filespec
419              Remove the directory filespec.
420
421       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
426       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
431       set_current_time time
432              Set current time in seconds since Unix epoch to use when setting
433              filesystem fields.
434
435       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
439       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
445       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
451       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
457       show_debugfs_params
458              Display debugfs parameters such as information  about  currently
459              opened filesystem.
460
461       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
466       stat filespec
467              Display  the  contents of the inode structure of the inode file‐
468              spec.
469
470       supported_features
471              Display  filesystem  features  supported  by  this  version   of
472              debugfs.
473
474       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
479       testi filespec
480              Test  if  the inode filespec is marked as allocated in the inode
481              bitmap.
482
483       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
490              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
500       unlink pathname
501              Remove the link specified by pathname to an  inode.   Note  this
502              does not adjust the inode reference counts.
503
504       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
508       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
516       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

ENVIRONMENT VARIABLES

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

AUTHOR

540       debugfs was written by Theodore Ts'o <tytso@mit.edu>.
541

SEE ALSO

543       dumpe2fs(8), tune2fs(8), e2fsck(8), mke2fs(8), ext4(5)
544
545
546
547E2fsprogs version 1.45.3           July 2019                        DEBUGFS(8)
Impressum