debugfs/debugfs.8.in

   1 .\" -*- nroff -*-
   2 .\" Copyright 1993, 1994, 1995 by Theodore Ts'o.  All Rights Reserved.
   3 .\" This file may be copied under the terms of the GNU Public License.
   4 .\"
   5 .TH DEBUGFS 8 "@E2FSPROGS_MONTH@ @E2FSPROGS_YEAR@" "E2fsprogs version @E2FSPROGS_VERSION@"
   6 .SH NAME
   7 debugfs \- ext2/ext3/ext4 file system debugger
   8 .SH SYNOPSIS
   9 .B debugfs
  10 [
  11 .B \-DVwcin
  12 ]
  13 [
  14 .B \-b
  15 blocksize
  16 ]
  17 [
  18 .B \-s
  19 superblock
  20 ]
  21 [
  22 .B \-f
  23 cmd_file
  24 ]
  25 [
  26 .B \-R
  27 request
  28 ]
  29 [
  30 .B \-d
  31 data_source_device
  32 ]
  33 [
  34 device
  35 ]
  36 .SH DESCRIPTION
  37 The
  38 .B debugfs
  39 program is an interactive file system debugger. It can be used to
  40 examine and change the state of an ext2, ext3, or ext4 file system.
  41 .br
  42 .I device
  43 is the special file corresponding to the device containing the
  44 file system (e.g /dev/hdXX).
  45 .SH OPTIONS
  46 .TP
  47 .I \-w
  48 Specifies that the file system should be opened in read-write mode.
  49 Without this option, the file system is opened in read-only mode.
  50 .TP
  51 .I \-n
  52 Disables metadata checksum verification.  This should only be used if
  53 you believe the metadata to be correct despite the complaints of
  54 e2fsprogs.
  55 .TP
  56 .I \-c
  57 Specifies that the file system should be opened in catastrophic mode, in
  58 which the inode and group bitmaps are not read initially.  This can be
  59 useful for filesystems with significant corruption, but because of this,
  60 catastrophic mode forces the filesystem to be opened read-only.
  61 .TP
  62 .I \-i
  63 Specifies that
  64 .I device
  65 represents an ext2 image file created by the
  66 .B e2image
  67 program.  Since the ext2 image file only contains the superblock, block
  68 group descriptor, block and inode allocation bitmaps, and
  69 the inode table, many
  70 .B debugfs
  71 commands will not function properly.
  72 .B Warning:
  73 no safety checks are in place, and
  74 .B debugfs
  75 may fail in interesting ways if commands such as
  76 .IR ls ", " dump ", "
  77 etc. are tried without specifying the
  78 .I data_source_device
  79 using the
  80 .I \-d
  81 option.
  82 .B debugfs
  83 is a debugging tool.  It has rough edges!
  84 .TP
  85 .I -d data_source_device
  86 Used with the
  87 .I \-i
  88 option, specifies that
  89 .I data_source_device
  90 should be used when reading blocks not found in the ext2 image file.
  91 This includes data, directory, and indirect blocks.
  92 .TP
  93 .I -b blocksize
  94 Forces the use of the given block size for the file system, rather than
  95 detecting the correct block size as normal.
  96 .TP
  97 .I -s superblock
  98 Causes the file system superblock to be read from the given block
  99 number, instead of using the primary superblock (located at an offset of
 100 1024 bytes from the beginning of the filesystem).  If you specify the
 101 .I -s
 102 option, you must also provide the blocksize of the filesystem via the
 103 .I -b
 104 option.
 105 .TP
 106 .I -f cmd_file
 107 Causes
 108 .B debugfs
 109 to read in commands from
 110 .IR cmd_file ,
 111 and execute them.  When
 112 .B debugfs
 113 is finished executing those commands, it will exit.
 114 .TP
 115 .I -D
 116 Causes
 117 .B debugfs
 118 to open the device using Direct I/O, bypassing the buffer cache.  Note
 119 that some Linux devices, notably device mapper as of this writing, do
 120 not support Direct I/O.
 121 .TP
 122 .I -R request
 123 Causes
 124 .B debugfs
 125 to execute the single command
 126 .IR request ,
 127 and then exit.
 128 .TP
 129 .I -V
 130 print the version number of
 131 .B debugfs
 132 and exit.
 133 .SH SPECIFYING FILES
 134 Many
 135 .B debugfs
 136 commands take a
 137 .I filespec
 138 as an argument to specify an inode (as opposed to a pathname)
 139 in the filesystem which is currently opened by
 140 .BR debugfs .
 141 The
 142 .I filespec
 143 argument may be specified in two forms.  The first form is an inode
 144 number surrounded by angle brackets, e.g.,
 145 .IR <2> .
 146 The second form is a pathname; if the pathname is prefixed by a forward slash
 147 ('/'), then it is interpreted relative to the root of the filesystem
 148 which is currently opened by
 149 .BR debugfs .
 150 If not, the pathname is
 151 interpreted relative to the current working directory as maintained by
 152 .BR debugfs .
 153 This may be modified by using the
 154 .B debugfs
 155 command
 156 .IR cd .
 157 .\"
 158 .\"
 159 .\"
 160 .SH COMMANDS
 161 This is a list of the commands which
 162 .B debugfs
 163 supports.
 164 .TP
 165 .I blocks filespace
 166 Print the blocks used by the inode
 167 .I filespec
 168 to stdout.
 169 .TP
 170 .I bmap filespec logical_block
 171 Print the physical block number corresponding to the logical block number
 172 .I logical_block
 173 in the inode
 174 .IR filespec .
 175 .TP
 176 .I cat filespec
 177 Dump the contents of the inode
 178 .I filespec
 179 to stdout.
 180 .TP
 181 .I cd filespec
 182 Change the current working directory to
 183 .IR filespec .
 184 .TP
 185 .I chroot filespec
 186 Change the root directory to be the directory
 187 .IR filespec .
 188 .TP
 189 .I close [-a]
 190 Close the currently open file system.  If the
 191 .I -a
 192 option is specified, write out any changes to the superblock and block
 193 group descriptors to all of the backup superblocks, not just to the
 194 master superblock.
 195 .TP
 196 .I clri file
 197 Clear the contents of the inode
 198 .IR file .
 199 .TP
 200 .I dirsearch filespec filename
 201 Search the directory
 202 .I filespec
 203 for
 204 .IR filename .
 205 .TP
 206 .I dump [-p] filespec out_file
 207 Dump the contents of the inode
 208 .I filespec
 209 to the output file
 210 .IR out_file .
 211 If the
 212 .I -p
 213 option is given set the owner, group and permissions information on
 214 .I out_file
 215 to match
 216 .IR filespec .
 217 .TP
 218 .I dump_mmp
 219 Display the multiple-mount protection (mmp) field values.
 220 .TP
 221 .I dx_hash [-h hash_alg] [-s hash_seed] filename
 222 Calculate the directory hash of
 223 .IR filename .
 224 The hash algorithm specified with
 225 .I -h
 226 may be "legacy" "half_md4" or "tea".
 227 The hash seed specified with
 228 .I -s
 229 must be in UUID format.
 230 .TP
 231 .I dump_extents [-n] [-l] filespec
 232 Dump the the extent tree of the inode
 233 .IR filespec .
 234 The
 235 .I -n
 236 flag will cause
 237 .I dump_extents
 238 to only display the interior nodes in the extent tree.   The
 239 .I  -l
 240 flag cause
 241 .I dump_extents
 242 to only display the leaf nodes in the extent tree.
 243 .IP
 244 (Please note that the length and range of blocks for the last extent in
 245 an interior node is an estimate by the extents library functions, and is
 246 not stored in filesystem data structures.   Hence, the values displayed
 247 may not necessarily by accurate and does not indicate a problem or
 248 corruption in the file system.)
 249 .TP
 250 .I expand_dir filespec
 251 Expand the directory
 252 .IR filespec .
 253 .TP
 254 .I feature [fs_feature] [-fs_feature] ...
 255 Set or clear various filesystem features in the superblock.  After setting
 256 or clearing any filesystem features that were requested, print the current
 257 state of the filesystem feature set.
 258 .TP
 259 .I filefrag [-dvr] filespec
 260 Print the number of contiguous extents in
 261 .IR filespec .
 262 If
 263 .I filespec
 264 is a directory and the
 265 .I -d
 266 option is not specified,
 267 .I filefrag
 268 will print the number of contiguous extents for each file in
 269 the directory.  The
 270 .I -v
 271 option will cause
 272 .I filefrag
 273 print a tabular listing of the contiguous extents in the
 274 file.  The
 275 .I -r
 276 option will cause
 277 .I filefrag
 278 to do a recursive listing of the directory.
 279 .TP
 280 .I find_free_block [count [goal]]
 281 Find the first
 282 .I count
 283 free blocks, starting from
 284 .I goal
 285 and allocate it.
 286 .TP
 287 .I find_free_inode [dir [mode]]
 288 Find a free inode and allocate it.  If present,
 289 .I dir
 290 specifies the inode number of the directory
 291 which the inode is to be located.  The second
 292 optional argument
 293 .I mode
 294 specifies the permissions of the new inode.  (If the directory bit is set
 295 on the mode, the allocation routine will function differently.)
 296 .TP
 297 .I freeb block [count]
 298 Mark the block number
 299 .I block
 300 as not allocated.
 301 If the optional argument
 302 .I count
 303 is present, then
 304 .I count
 305 blocks starting at block number
 306 .I block
 307 will be marked as not allocated.
 308 .TP
 309 .I freefrag [-c chunk_kb ]
 310 Report free space fragmentation on the currently open file system.
 311 If the
 312 .I \-c
 313 option is specified then the filefrag command will print how many free
 314 chunks of size
 315 .I chunk_kb
 316 can be found in the file system.  The chunk size must be a power of two
 317 and be larger than the file system block size.
 318 .TP
 319 .I freei filespec [num]
 320 Free the inode specified by
 321 .IR filespec .
 322 If
 323 .I num
 324 is specified, also clear num-1 inodes after the specified inode.
 325 .TP
 326 .I help
 327 Print a list of commands understood by
 328 .BR debugfs .
 329 .TP
 330 .I htree_dump filespec
 331 Dump the hash-indexed directory
 332 .IR filespec ,
 333 showing its tree structure.
 334 .TP
 335 .I icheck block ...
 336 Print a listing of the inodes which use the one or more blocks specified
 337 on the command line.
 338 .TP
 339 .I imap filespec
 340 Print the location of the inode data structure (in the inode table)
 341 of the inode
 342 .IR filespec .
 343 .TP
 344 .I init_filesys device blocksize
 345 Create an ext2 file system on
 346 .I device
 347 with device size
 348 .IR blocksize .
 349 Note that this does not fully initialize all of the data structures;
 350 to do this, use the
 351 .BR mke2fs (8)
 352 program.  This is just a call to the low-level library, which sets up
 353 the superblock and block descriptors.
 354 .TP
 355 .I kill_file filespec
 356 Deallocate the inode
 357 .I filespec
 358 and its blocks.  Note that this does not remove any directory
 359 entries (if any) to this inode.  See the
 360 .BR rm (1)
 361 command if you wish to unlink a file.
 362 .TP
 363 .I lcd directory
 364 Change the current working directory of the
 365 .B debugfs
 366 process to
 367 .I directory
 368 on the native filesystem.
 369 .TP
 370 .I ln filespec dest_file
 371 Create a link named
 372 .I dest_file
 373 which is a link to
 374 .IR filespec .
 375 Note this does not adjust the inode reference counts.
 376 .TP
 377 .I logdump [-acs] [-b<block>] [-i<filespec>] [-f<journal_file>] [output_file]
 378 Dump the contents of the ext3 journal.  By default, the journal inode as
 379 specified in the superblock.  However, this can be overridden with the
 380 .I \-i
 381 option, which uses an inode specifier to specify the journal to be
 382 used.  A file containing journal data can be specified using the
 383 .I \-f
 384 option.   Finally, the
 385 .I \-s
 386 option utilizes the backup information in the superblock to locate the
 387 journal.
 388 .IP
 389 The
 390 .I \-a
 391 option causes the
 392 .I logdump
 393 program to print the contents of all of the descriptor blocks.
 394 The
 395 .I \-b
 396 option causes
 397 .I logdump
 398 to print all journal records that are refer to the specified block.
 399 The
 400 .I \-c
 401 option will print out the contents of all of the data blocks selected by
 402 the
 403 .I \-a
 404 and
 405 .I \-b
 406 options.
 407 .TP
 408 .I ls [-l] [-c] [-d] [-p] filespec
 409 Print a listing of the files in the directory
 410 .IR filespec .
 411 The
 412 .I \-l
 413 flag will list files using a more verbose format.
 414 The
 415 .I \-c
 416 flag causes directory block checksums (if present) to be displayed.
 417 The
 418 .I \-d
 419 flag will list deleted entries in the directory.
 420 The
 421 .I \-p
 422 flag will list the files in a format which is more easily parsable by
 423 scripts, as well as making it more clear when there are spaces or other
 424 non-printing characters at the end of filenames.
 425 .TP
 426 .I modify_inode filespec
 427 Modify the contents of the inode structure in the inode
 428 .IR filespec .
 429 .TP
 430 .I mkdir filespec
 431 Make a directory.
 432 .TP
 433 .I mknod filespec [p|[[c|b] major minor]]
 434 Create a special device file (a named pipe, character or block device).
 435 If a character or block device is to be made, the
 436 .I major
 437 and
 438 .I minor
 439 device numbers must be specified.
 440 .TP
 441 .I ncheck [-c] inode_num ...
 442 Take the requested list of inode numbers, and print a listing of pathnames
 443 to those inodes.  The
 444 .I -c
 445 flag will enable checking the file type information in the directory
 446 entry to make sure it matches the inode's type.
 447 .TP
 448 .I open [-w] [-e] [-f] [-i] [-c] [-D] [-b blocksize] [-s superblock] device
 449 Open a filesystem for editing.  The
 450 .I -f
 451 flag forces the filesystem to be opened even if there are some unknown
 452 or incompatible filesystem features which would normally
 453 prevent the filesystem from being opened.  The
 454 .I -e
 455 flag causes the filesystem to be opened in exclusive mode.  The
 456 .IR -b ", " -c ", " -i ", " -s ", " -w ", and " -D
 457 options behave the same as the command-line options to
 458 .BR debugfs .
 459 .TP
 460 .I punch filespec start_blk [end_blk]
 461 Delete the blocks in the inode ranging from
 462 .I start_blk
 463 to
 464 .IR end_blk .
 465 If
 466 .I end_blk
 467 is omitted then this command will function as a truncate command; that
 468 is, all of the blocks starting at
 469 .I start_blk
 470 through to the end of the file will be deallocated.
 471 .TP
 472 .I pwd
 473 Print the current working directory.
 474 .TP
 475 .I quit
 476 Quit
 477 .B debugfs
 478 .TP
 479 .I rdump directory destination
 480 Recursively dump
 481 .I directory
 482 and all its contents (including regular files, symbolic links, and other
 483 directories) into the named
 484 .I destination
 485 which should be an existing directory on the native filesystem.
 486 .TP
 487 .I rm pathname
 488 Unlink
 489 .IR pathname .
 490 If this causes the inode pointed to by
 491 .I pathname
 492 to have no other references, deallocate the file.  This command functions
 493 as the unlink() system call.
 494 .I
 495 .TP
 496 .I rmdir filespec
 497 Remove the directory
 498 .IR filespec .
 499 .TP
 500 .I setb block [count]
 501 Mark the block number
 502 .I block
 503 as allocated.
 504 If the optional argument
 505 .I count
 506 is present, then
 507 .I count
 508 blocks starting at block number
 509 .I block
 510 will be marked as allocated.
 511 .TP
 512 .I set_block_group bgnum field value
 513 Modify the block group descriptor specified by
 514 .I bgnum
 515 so that the block group descriptor field
 516 .I field
 517 has value
 518 .I value.
 519 .TP
 520 .I seti filespec [num]
 521 Mark inode
 522 .I filespec
 523 as in use in the inode bitmap.  If
 524 .I num
 525 is specified, also set num-1 inodes after the specified inode.
 526 .TP
 527 .I set_inode_field filespec field value
 528 Modify the inode specified by
 529 .I filespec
 530 so that the inode field
 531 .I field
 532 has value
 533 .I value.
 534 The list of valid inode fields which can be set via this command
 535 can be displayed by using the command:
 536 .B set_inode_field -l
 537 .TP
 538 .I set_mmp_value field value
 539 Modify the multiple-mount protection (mmp) data so that the
 540 mmp field
 541 .I field
 542 has value
 543 .I value.
 544 The list of valid mmp fields which can be set via this command
 545 can be displayed by using the command:
 546 .B set_mmp_value -l
 547 .TP
 548 .I set_super_value field value
 549 Set the superblock field
 550 .I field
 551 to
 552 .I value.
 553 The list of valid superblock fields which can be set via this command
 554 can be displayed by using the command:
 555 .B set_super_value -l
 556 .TP
 557 .I show_super_stats [-h]
 558 List the contents of the super block and the block group descriptors.  If the
 559 .I -h
 560 flag is given, only print out the superblock contents.
 561 .TP
 562 .I stat filespec
 563 Display the contents of the inode structure of the inode
 564 .IR filespec .
 565 .TP
 566 .I testb block [count]
 567 Test if the block number
 568 .I block
 569 is marked as allocated in the block bitmap.
 570 If the optional argument
 571 .I count
 572 is present, then
 573 .I count
 574 blocks starting at block number
 575 .I block
 576 will be tested.
 577 .TP
 578 .I testi filespec
 579 Test if the inode
 580 .I filespec
 581 is marked as allocated in the inode bitmap.
 582 .TP
 583 .I undel <inode num> [pathname]
 584 Undelete the specified inode number (which must be surrounded by angle
 585 brackets) so that it and its blocks are marked in use, and optionally
 586 link the recovered inode to the specified pathname.  The
 587 .B e2fsck
 588 command should always be run after using the
 589 .B undel
 590 command to recover deleted files.
 591 .IP
 592 Note that if you are recovering a large number of deleted files, linking
 593 the inode to a directory may require the directory to be expanded, which
 594 could allocate a block that had been used by one of the
 595 yet-to-be-undeleted files.  So it is safer to undelete all of the
 596 inodes without specifying a destination pathname, and then in a separate
 597 pass, use the debugfs
 598 .B link
 599 command to link the inode to the destination pathname, or use
 600 .B e2fsck
 601 to check the filesystem and link all of the recovered inodes to the
 602 lost+found directory.
 603 .TP
 604 .I unlink pathname
 605 Remove the link specified by
 606 .I pathname
 607 to an inode.  Note this does not adjust the inode reference counts.
 608 .TP
 609 .I write source_file out_file
 610 Create a file in the filesystem named
 611 .IR out_file ,
 612 and copy the contents of
 613 .I source_file
 614 into the destination file.
 615 .SH ENVIRONMENT VARIABLES
 616 .TP
 617 .B DEBUGFS_PAGER, PAGER
 618 The
 619 .B debugfs
 620 program always pipes the output of the some commands through a
 621 pager program.  These commands include:
 622 .IR show_super_stats ,
 623 .IR list_directory ,
 624 .IR show_inode_info ,
 625 .IR list_deleted_inodes ,
 626 and
 627 .IR htree_dump .
 628 The specific pager can explicitly specified by the
 629 .B DEBUGFS_PAGER
 630 environment variable, and if it is not set, by the
 631 .B PAGER
 632 environment variable.
 633 .IP
 634 Note that since a pager is always used, the
 635 .BR less (1)
 636 pager is not particularly appropriate, since it clears the screen before
 637 displaying the output of the command and clears the output the screen
 638 when the pager is exited.  Many users prefer to use the
 639 .BR less (1)
 640 pager for most purposes, which is why the
 641 .B DEBUGFS_PAGER
 642 environment variable is available to override the more general
 643 .B PAGER
 644 environment variable.
 645 .SH AUTHOR
 646 .B debugfs
 647 was written by Theodore Ts'o <tytso@mit.edu>.
 648 .SH SEE ALSO
 649 .BR dumpe2fs (8),
 650 .BR tune2fs (8),
 651 .BR e2fsck (8),
 652 .BR mke2fs (8)