diff options
Diffstat (limited to 'upstream/debian-bookworm/man8/debugfs.8')
| -rw-r--r-- | upstream/debian-bookworm/man8/debugfs.8 | 880 |
1 files changed, 880 insertions, 0 deletions
diff --git a/upstream/debian-bookworm/man8/debugfs.8 b/upstream/debian-bookworm/man8/debugfs.8 new file mode 100644 index 00000000..8b6a600d --- /dev/null +++ b/upstream/debian-bookworm/man8/debugfs.8 @@ -0,0 +1,880 @@ +.\" -*- nroff -*- +.\" Copyright 1993, 1994, 1995 by Theodore Ts'o. All Rights Reserved. +.\" This file may be copied under the terms of the GNU Public License. +.\" +.TH DEBUGFS 8 "February 2023" "E2fsprogs version 1.47.0" +.SH NAME +debugfs \- ext2/ext3/ext4 file system debugger +.SH SYNOPSIS +.B debugfs +[ +.B \-DVwcin +] +[ +.B \-b +blocksize +] +[ +.B \-s +superblock +] +[ +.B \-f +cmd_file +] +[ +.B \-R +request +] +[ +.B \-d +data_source_device +] +[ +.B \-z +.I undo_file +] +[ +device +] +.SH DESCRIPTION +The +.B debugfs +program is an interactive file system debugger. It can be used to +examine and change the state of an ext2, ext3, or ext4 file system. +.PP +.I device +is a block device (e.g., /dev/sdXX) or a file containing the file system. +.SH OPTIONS +.TP +.I \-w +Specifies that the file system should be opened in read-write mode. +Without this option, the file system is opened in read-only mode. +.TP +.I \-n +Disables metadata checksum verification. This should only be used if +you believe the metadata to be correct despite the complaints of +e2fsprogs. +.TP +.I \-c +Specifies that the file system should be opened in catastrophic mode, in +which the inode and group bitmaps are not read initially. This can be +useful for file systems with significant corruption, but because of this, +catastrophic mode forces the file system to be opened read-only. +.TP +.I \-i +Specifies that +.I device +represents an ext2 image file created by the +.B e2image +program. Since the ext2 image file only contains the superblock, block +group descriptor, block and inode allocation bitmaps, and +the inode table, many +.B debugfs +commands will not function properly. +.B Warning: +no safety checks are in place, and +.B debugfs +may fail in interesting ways if commands such as +.IR ls ", " dump ", " +etc. are tried without specifying the +.I data_source_device +using the +.I \-d +option. +.B debugfs +is a debugging tool. It has rough edges! +.TP +.I -d data_source_device +Used with the +.I \-i +option, specifies that +.I data_source_device +should be used when reading blocks not found in the ext2 image file. +This includes data, directory, and indirect blocks. +.TP +.I -b blocksize +Forces the use of the given block size (in bytes) for the file system, +rather than detecting the correct block size automatically. (This +option is rarely needed; it is used primarily when the file system is +extremely badly damaged/corrupted.) +.TP +.I -s superblock +Causes the file system superblock to be read from the given block +number, instead of using the primary superblock (located at an offset of +1024 bytes from the beginning of the file system). If you specify the +.I -s +option, you must also provide the blocksize of the file system via the +.I -b +option. (This +option is rarely needed; it is used primarily when the file system is +extremely badly damaged/corrupted.) +.TP +.I -f cmd_file +Causes +.B debugfs +to read in commands from +.IR cmd_file , +and execute them. When +.B debugfs +is finished executing those commands, it will exit. +.TP +.I -D +Causes +.B debugfs +to open the device using Direct I/O, bypassing the buffer cache. Note +that some Linux devices, notably device mapper as of this writing, do +not support Direct I/O. +.TP +.I -R request +Causes +.B debugfs +to execute the single command +.IR request , +and then exit. +.TP +.I -V +print the version number of +.B debugfs +and exit. +.TP +.BI \-z " undo_file" +Before overwriting a file system block, write the old contents of the block to +an undo file. This undo file can be used with e2undo(8) to restore the old +contents of the file system should something go wrong. If the empty string is +passed as the undo_file argument, the undo file will be written to a file named +debugfs-\fIdevice\fR.e2undo in the directory specified via the +\fIE2FSPROGS_UNDO_DIR\fR environment variable. + +WARNING: The undo file cannot be used to recover from a power or system crash. +.SH SPECIFYING FILES +Many +.B debugfs +commands take a +.I filespec +as an argument to specify an inode (as opposed to a pathname) +in the file system which is currently opened by +.BR debugfs . +The +.I filespec +argument may be specified in two forms. The first form is an inode +number surrounded by angle brackets, e.g., +.IR <2> . +The second form is a pathname; if the pathname is prefixed by a forward slash +('/'), then it is interpreted relative to the root of the file system +which is currently opened by +.BR debugfs . +If not, the pathname is +interpreted relative to the current working directory as maintained by +.BR debugfs . +This may be modified by using the +.B debugfs +command +.IR cd . +.\" +.\" +.\" +.SH COMMANDS +This is a list of the commands which +.B debugfs +supports. +.TP +.BI blocks " filespec" +Print the blocks used by the inode +.I filespec +to stdout. +.TP +.BI bmap " [ -a ] filespec logical_block [physical_block]" +Print or set the physical block number corresponding to the logical block number +.I logical_block +in the inode +.IR filespec . +If the +.I \-a +flag is specified, try to allocate a block if necessary. +.TP +.BI block_dump " '[ -x ] [-f filespec] block_num" +Dump the file system block given by +.I block_num +in hex and ASCII format to the console. If the +.I \-f +option is specified, the block number is relative to the start of the given +.BR filespec . +If the +.I \-x +option is specified, the block is interpreted as an extended attribute +block and printed to show the structure of extended attribute data +structures. +.TP +.BI cat " filespec" +Dump the contents of the inode +.I filespec +to stdout. +.TP +.BI cd " filespec" +Change the current working directory to +.IR filespec . +.TP +.BI chroot " filespec" +Change the root directory to be the directory +.IR filespec . +.TP +.BI close " [-a]" +Close the currently open file system. If the +.I -a +option is specified, write out any changes to the superblock and block +group descriptors to all of the backup superblocks, not just to the +master superblock. +.TP +.BI clri " filespec" +Clear the contents of the inode +.IR filespec . +.TP +.BI copy_inode " source_inode destination_inode" +Copy the contents of the inode structure in +.I source_inode +and use it to overwrite the inode structure at +.IR destination_inode . +.TP +.BI dirsearch " filespec filename" +Search the directory +.I filespec +for +.IR filename . +.TP +.BI dirty " [-clean]" +Mark the file system as dirty, so that the superblocks will be written on exit. +Additionally, clear the superblock's valid flag, or set it if +.I -clean +is specified. +.TP +.BI dump " [-p] filespec out_file" +Dump the contents of the inode +.I filespec +to the output file +.IR out_file . +If the +.I -p +option is given set the owner, group and permissions information on +.I out_file +to match +.IR filespec . +.TP +.BI dump_mmp " [mmp_block]" +Display the multiple-mount protection (mmp) field values. If +.I mmp_block +is specified then verify and dump the MMP values from the given block +number, otherwise use the +.B s_mmp_block +field in the superblock to locate and use the existing MMP block. +.TP +.BI dx_hash " [-h hash_alg] [-s hash_seed] filename" +Calculate the directory hash of +.IR filename . +The hash algorithm specified with +.I -h +may be +.BR legacy , " half_md4" ", or " tea . +The hash seed specified with +.I -s +must be in UUID format. +.TP +.BI dump_extents " [-n] [-l] filespec" +Dump the extent tree of the inode +.IR filespec . +The +.I -n +flag will cause +.B dump_extents +to only display the interior nodes in the extent tree. The +.I -l +flag will cause +.B dump_extents +to only display the leaf nodes in the extent tree. +.IP +(Please note that the length and range of blocks for the last extent in +an interior node is an estimate by the extents library functions, and is +not stored in file system data structures. Hence, the values displayed +may not necessarily by accurate and does not indicate a problem or +corruption in the file system.) +.TP +.B dump_unused +Dump unused blocks which contain non-null bytes. +.TP +.BI ea_get " [-f outfile]|[-xVC] [-r] filespec attr_name" +Retrieve the value of the extended attribute +.I attr_name +in the file +.I filespec +and write it either to stdout or to \fIoutfile\fR. +.TP +.BI ea_list " filespec +List the extended attributes associated with the file +.I filespec +to standard output. +.TP +.BI ea_set " [-f infile] [-r] filespec attr_name attr_value +Set the value of the extended attribute +.I attr_name +in the file +.I filespec +to the string value +.I attr_value +or read it from \fIinfile\fR. +.TP +.BI ea_rm " filespec attr_names... +Remove the extended attribute +.I attr_name +from the file \fIfilespec\fR. +.TP +.BI expand_dir " filespec" +Expand the directory +.IR filespec . +.TP +.BI fallocate " filespec start_block [end_block] +Allocate and map uninitialized blocks into \fIfilespec\fR between +logical block \fIstart_block\fR and \fIend_block\fR, inclusive. If +\fIend_block\fR is not supplied, this function maps until it runs out +of free disk blocks or the maximum file size is reached. Existing +mappings are left alone. +.TP +.BI feature " [fs_feature] [-fs_feature] ..." +Set or clear various file system features in the superblock. After setting +or clearing any file system features that were requested, print the current +state of the file system feature set. +.TP +.BI filefrag " [-dvr] filespec" +Print the number of contiguous extents in +.IR filespec . +If +.I filespec +is a directory and the +.I -d +option is not specified, +.I filefrag +will print the number of contiguous extents for each file in +the directory. The +.I -v +option will cause +.I filefrag +print a tabular listing of the contiguous extents in the +file. The +.I -r +option will cause +.I filefrag +to do a recursive listing of the directory. +.TP +.BI find_free_block " [count [goal]]" +Find the first +.I count +free blocks, starting from +.I goal +and allocate it. Also available as +.BR ffb . +.TP +.BI find_free_inode " [dir [mode]]" +Find a free inode and allocate it. If present, +.I dir +specifies the inode number of the directory +which the inode is to be located. The second +optional argument +.I mode +specifies the permissions of the new inode. (If the directory bit is set +on the mode, the allocation routine will function differently.) Also +available as +.BR ffi . +.TP +.BI freeb " block [count]" +Mark the block number +.I block +as not allocated. +If the optional argument +.I count +is present, then +.I count +blocks starting at block number +.I block +will be marked as not allocated. +.TP +.BI freefrag " [-c chunk_kb]" +Report free space fragmentation on the currently open file system. +If the +.I \-c +option is specified then the filefrag command will print how many free +chunks of size +.I chunk_kb +can be found in the file system. The chunk size must be a power of two +and be larger than the file system block size. +.TP +.BI freei " filespec [num]" +Free the inode specified by +.IR filespec . +If +.I num +is specified, also clear num-1 inodes after the specified inode. +.TP +.BI get_quota " quota_type id" +Display quota information for given quota type (user, group, or project) and ID. +.TP +.B help +Print a list of commands understood by +.BR debugfs . +.TP +.BI htree_dump " filespec" +Dump the hash-indexed directory +.IR filespec , +showing its tree structure. +.TP +.BI icheck " block ..." +Print a listing of the inodes which use the one or more blocks specified +on the command line. +.TP +.BI inode_dump " [-b]|[-e]|[-x] filespec" +Print the contents of the inode data structure in hex and ASCII format. +The +.I \-b +option causes the command to only dump the contents of the +.B i_blocks +array. The +.I \-e +option causes the command to only dump the contents of the extra inode +space, which is used to store in-line extended attributes. The +.I \-x +option causes the command to dump the extra inode space interpreted and +extended attributes. This is useful to debug corrupted inodes +containing extended attributes. +.TP +.BI imap " filespec" +Print the location of the inode data structure (in the inode table) +of the inode +.IR filespec . +.TP +.BI init_filesys " device blocksize" +Create an ext2 file system on +.I device +with device size +.IR blocksize . +Note that this does not fully initialize all of the data structures; +to do this, use the +.BR mke2fs (8) +program. This is just a call to the low-level library, which sets up +the superblock and block descriptors. +.TP +.BI journal_close +Close the open journal. +.TP +.BI journal_open " [-c] [-v ver] [-f ext_jnl] +Opens the journal for reading and writing. Journal checksumming can +be enabled by supplying \fI-c\fR; checksum formats 2 and 3 can be +selected with the \fI-v\fR option. An external journal can be loaded +from \fIext_jnl\fR. +.TP +.BI journal_run +Replay all transactions in the open journal. +.TP +.BI journal_write " [-b blocks] [-r revoke] [-c] file +Write a transaction to the open journal. The list of blocks to write +should be supplied as a comma-separated list in \fIblocks\fR; the +blocks themselves should be readable from \fIfile\fR. A list of +blocks to revoke can be supplied as a comma-separated list in +\fIrevoke\fR. By default, a commit record is written at the end; the +\fI-c\fR switch writes an uncommitted transaction. +.TP +.BI kill_file " filespec" +Deallocate the inode +.I filespec +and its blocks. Note that this does not remove any directory +entries (if any) to this inode. See the +.BR rm (1) +command if you wish to unlink a file. +.TP +.BI lcd " directory" +Change the current working directory of the +.B debugfs +process to +.I directory +on the native file system. +.TP +.BI list_quota " quota_type" +Display quota information for given quota type (user, group, or project). +.TP +.BI ln " filespec dest_file" +Create a link named +.I dest_file +which is a hard link to +.IR filespec . +Note this does not adjust the inode reference counts. +.TP +.BI logdump " [-acsOS] [-b block] [-n num_trans ] [-i filespec] [-f journal_file] [output_file]" +Dump the contents of the ext3 journal. By default, dump the journal inode as +specified in the superblock. However, this can be overridden with the +.I \-i +option, which dumps the journal from the internal inode given by +.IR filespec . +A regular file containing journal data can be specified using the +.I \-f +option. Finally, the +.I \-s +option utilizes the backup information in the superblock to locate the +journal. +.IP +The +.I \-S +option causes +.B logdump +to print the contents of the journal superblock. +.IP +The +.I \-a +option causes the +.B logdump +to print the contents of all of the descriptor blocks. +The +.I \-b +option causes +.B logdump +to print all journal records that refer to the specified block. +The +.I \-c +option will print out the contents of all of the data blocks selected by +the +.I \-a +and +.I \-b +options. +.IP +The +.I \-O +option causes logdump to display old (checkpointed) journal entries. +This can be used to try to track down journal problems even after the +journal has been replayed. +.IP +The +.I \-n +option causes +.B logdump +to continue past a journal block which is missing a magic number. +Instead, it will stop only when the entire log is printed or after +.I num_trans +transactions. +.TP +.BI ls " [-l] [-c] [-d] [-p] [-r] filespec" +Print a listing of the files in the directory +.IR filespec . +The +.I \-c +flag causes directory block checksums (if present) to be displayed. +The +.I \-d +flag will list deleted entries in the directory. +The +.I \-l +flag will list files using a more verbose format. +The +.I \-p +flag will list the files in a format which is more easily parsable by +scripts, as well as making it more clear when there are spaces or other +non-printing characters at the end of filenames. +The +.I \-r +flag will force the printing of the filename, even if it is encrypted. +.TP +.BI list_deleted_inodes " [limit]" +List deleted inodes, optionally limited to those deleted within +.I limit +seconds ago. Also available as +.BR lsdel . +.IP +This command was useful for recovering from accidental file deletions +for ext2 file systems. Unfortunately, it is not useful for this purpose +if the files were deleted using ext3 or ext4, since the inode's +data blocks are no longer available after the inode is released. +.TP +.BI modify_inode " filespec" +Modify the contents of the inode structure in the inode +.IR filespec . +Also available as +.BR mi . +.TP +.BI mkdir " filespec" +Make a directory. +.TP +.BI mknod " filespec [p|[[c|b] major minor]]" +Create a special device file (a named pipe, character or block device). +If a character or block device is to be made, the +.I major +and +.I minor +device numbers must be specified. +.TP +.BI ncheck " [-c] inode_num ..." +Take the requested list of inode numbers, and print a listing of pathnames +to those inodes. The +.I -c +flag will enable checking the file type information in the directory +entry to make sure it matches the inode's type. +.TP +.BI open " [-weficD] [-b blocksize] [-d image_filename] [-s superblock] [-z undo_file] device" +Open a file system for editing. The +.I -f +flag forces the file system to be opened even if there are some unknown +or incompatible file system features which would normally +prevent the file system from being opened. The +.I -e +flag causes the file system to be opened in exclusive mode. The +.IR -b ", " -c ", " -d ", " -i ", " -s ", " -w ", and " -D +options behave the same as the command-line options to +.BR debugfs . +.TP +.BI punch " filespec start_blk [end_blk]" +Delete the blocks in the inode ranging from +.I start_blk +to +.IR end_blk . +If +.I end_blk +is omitted then this command will function as a truncate command; that +is, all of the blocks starting at +.I start_blk +through to the end of the file will be deallocated. +.TP +.BI symlink " filespec target" +Make a symbolic link. +.TP +.B pwd +Print the current working directory. +.TP +.B quit +Quit +.B debugfs +.TP +.BI rdump " directory[...] destination" +Recursively dump +.IR directory , +or multiple +.IR directories , +and all its contents (including regular files, symbolic links, and other +directories) into the named +.IR destination , +which should be an existing directory on the native file system. +.TP +.BI rm " pathname" +Unlink +.IR pathname . +If this causes the inode pointed to by +.I pathname +to have no other references, deallocate the file. This command functions +as the unlink() system call. +.I +.TP +.BI rmdir " filespec" +Remove the directory +.IR filespec . +.TP +.BI setb " block [count]" +Mark the block number +.I block +as allocated. +If the optional argument +.I count +is present, then +.I count +blocks starting at block number +.I block +will be marked as allocated. +.TP +.BI set_block_group " bgnum field value" +Modify the block group descriptor specified by +.I bgnum +so that the block group descriptor field +.I field +has value +.IR value . +Also available as +.BR set_bg . +.TP +.BI set_current_time " time" +Set current time in seconds since Unix epoch to use when setting file system +fields. +.TP +.BI seti " filespec [num]" +Mark inode +.I filespec +as in use in the inode bitmap. If +.I num +is specified, also set num-1 inodes after the specified inode. +.TP +.BI set_inode_field " filespec field value" +Modify the inode specified by +.I filespec +so that the inode field +.I field +has value +.I value. +The list of valid inode fields which can be set via this command +can be displayed by using the command: +.B set_inode_field -l +Also available as +.BR sif . +.TP +.BI set_mmp_value " field value" +Modify the multiple-mount protection (MMP) data so that the MMP field +.I field +has value +.I value. +The list of valid MMP fields which can be set via this command +can be displayed by using the command: +.B set_mmp_value -l +Also available as +.BR smmp . +.TP +.BI set_super_value " field value" +Set the superblock field +.I field +to +.I value. +The list of valid superblock fields which can be set via this command +can be displayed by using the command: +.B set_super_value -l +Also available as +.BR ssv . +.TP +.B show_debugfs_params +Display +.B debugfs +parameters such as information about currently opened file system. +.TP +.BI show_super_stats " [-h]" +List the contents of the super block and the block group descriptors. If the +.I -h +flag is given, only print out the superblock contents. Also available as +.BR stats . +.TP +.BI stat " filespec" +Display the contents of the inode structure of the inode +.IR filespec . +.TP +.B supported_features +Display file system features supported by this version of +.BR debugfs . +.TP +.BI testb " block [count]" +Test if the block number +.I block +is marked as allocated in the block bitmap. +If the optional argument +.I count +is present, then +.I count +blocks starting at block number +.I block +will be tested. +.TP +.BI testi " filespec" +Test if the inode +.I filespec +is marked as allocated in the inode bitmap. +.TP +.BI undel " <inode_number> [pathname]" +Undelete the specified inode number (which must be surrounded by angle +brackets) so that it and its blocks are marked in use, and optionally +link the recovered inode to the specified pathname. The +.B e2fsck +command should always be run after using the +.B undel +command to recover deleted files. +.IP +Note that if you are recovering a large number of deleted files, linking +the inode to a directory may require the directory to be expanded, which +could allocate a block that had been used by one of the +yet-to-be-undeleted files. So it is safer to undelete all of the +inodes without specifying a destination pathname, and then in a separate +pass, use the debugfs +.B link +command to link the inode to the destination pathname, or use +.B e2fsck +to check the file system and link all of the recovered inodes to the +lost+found directory. +.TP +.BI unlink " pathname" +Remove the link specified by +.I pathname +to an inode. Note this does not adjust the inode reference counts. +.TP +.BI write " source_file out_file" +Copy the contents of +.I source_file +into a newly-created file in the file system named +.IR out_file . +.TP +.BI zap_block " [-f filespec] [-o offset] [-l length] [-p pattern] block_num" +Overwrite the block specified by +.I block_num +with zero (NUL) bytes, or if +.I -p +is given use the byte specified by +.IR pattern . +If +.I -f +is given then +.I block_num +is relative to the start of the file given by +.IR filespec . +The +.I -o +and +.I -l +options limit the range of bytes to zap to the specified +.I offset +and +.I length +relative to the start of the block. +.TP +.BI zap_block " [-f filespec] [-b bit] block_num" +Bit-flip portions of the physical +.IR block_num . +If +.I -f +is given, then +.I block_num +is a logical block relative to the start of +.IR filespec . +.SH ENVIRONMENT VARIABLES +.TP +.B DEBUGFS_PAGER, PAGER +The +.B debugfs +program always pipes the output of the some commands through a +pager program. These commands include: +.IR show_super_stats " (" stats ), +.IR list_directory " (" ls ), +.IR show_inode_info " (" stat ), +.IR list_deleted_inodes " (" lsdel ), +and +.IR htree_dump . +The specific pager can explicitly specified by the +.B DEBUGFS_PAGER +environment variable, and if it is not set, by the +.B PAGER +environment variable. +.IP +Note that since a pager is always used, the +.BR less (1) +pager is not particularly appropriate, since it clears the screen before +displaying the output of the command and clears the output the screen +when the pager is exited. Many users prefer to use the +.BR less (1) +pager for most purposes, which is why the +.B DEBUGFS_PAGER +environment variable is available to override the more general +.B PAGER +environment variable. +.SH AUTHOR +.B debugfs +was written by Theodore Ts'o <tytso@mit.edu>. +.SH SEE ALSO +.BR dumpe2fs (8), +.BR tune2fs (8), +.BR e2fsck (8), +.BR mke2fs (8), +.BR ext4 (5) |