Provided by: gfs2-utils_3.1.9-2ubuntu1_amd64 bug

NAME

       gfs2_edit - Display, print or edit GFS2 or GFS internal structures.

SYNOPSIS

       gfs2_edit [OPTION]... [DEVICE]

DESCRIPTION

       The  gfs2_edit command is a tool used to examine, edit or display internal data structures
       of a GFS2 or GFS file  system.   The  gfs2_edit  command  can  be  run  interactively,  as
       described below in INTERACTIVE MODE.

       Caution:  Several  options of the gfs2_edit command alter the file system metadata and can
       cause file system corruption.  These options should be used with great care.

OPTIONS

       -p  [struct  |  block]  [blocktype]  [blockalloc  [val]]   [blockbits]   [blockrg]   [find
       sb|rg|rb|di|in|lf|jd|lh|ld|ea|ed|lb|13|qc] [field <field> [val]]
              Print  a  gfs2  data  structure  in human-readable format to stdout.  You can enter
              either a block number or a data structure name.  Block numbers may be specified  in
              hex (e.g., 0x10) or decimal (e.g., 16).

              You can specify the following well-known locations with the -p option.

              sb, superblock - Print the superblock.

              root - Print the root directory.

              master - Print the master system directory.

              jindex - Print the journal index system directory.

              per_node - Print the per_node system directory.

              inum - Print the system inum file.

              statfs - Print the system statfs file.

              rindex, rgindex - Print the resource group index system file.

              rg X - Print the resource group information for RG X (zero-based).

              rgs - Print the resource group information.

              quota - Print the contents of the system quota file.

              identify - Identify a data block rather than print the block's contents.

              size - Print the device size information.

              journalX  -  Print the contents of journal X, where X is a journal number from 0 to
              <the number of journals in your file system - 1>.  Only  the  journal  headers  and
              journal  descriptors  are  dumped.  For journal descriptors, this option prints out
              every file system block number logged in that section of the journal.   The  actual
              journaled blocks are not printed.

              If  you  specify  a block number rather than a structure name, gfs2_edit will print
              out a breakdown of the structure for that block.  For example: gfs2_edit -p sb will
              print the superblock, but so does gfs2_edit -p 0x10 and gfs2_edit -p 16.

              If  you  specify  -p  without  a  block  or  structure  name,  gfs2_edit prints the
              superblock.

              You can specify more than one data structure with a single -p option.  For example,
              gfs2_edit  -p  inum  statfs  /dev/sda1  prints  the system inum file and the system
              statfs file on /dev/sda1.

              Optionally, you may specify the keyword blocktype to print out the gfs2 block  type
              for  the specified block.  Valid gfs2 block types are: 0 (Clump), 1 (Superblock), 2
              (Resource Group Header), 3 (Resource Group Bitmap), 4 (Dinode), 5 (Indirect Block),
              6  (Leaf),  7  (Journaled  data),  8 (Log Header), 9 (Log descriptor), 10 (Extended
              attribute), 11 (Eattr Data), 12 (Log Buffer), 13 (Invalid), and 14 (Quota Change).

              Optionally, you may specify the  keyword  blockalloc  with  an  optional  value  to
              assign.   If  no  value  is  specified, the blockalloc keyword will print the block
              allocation type for the specified block.  Valid block allocation types are: 0 (Free
              block),  1  (Data  block),  2 (Unlinked block), and 3 (Metadata block).  If a value
              from 0 to 3 is specified, the resource group bitmap will  be  changed  to  the  new
              value.   This may be used, for example, to artificially free or allocate a block in
              order to test fsck.gfs2's ability to detect and fix the problem.

              Optionally, you may specify the keyword blockbits.  This  option  will  locate  and
              print the block containing the bitmap corresponding to the specified block.

              Optionally, you may specify the keyword blockrg.  This option will locate and print
              the block number of the resource group that holds information about  the  specified
              block.

              You  may  also  use  gfs2_edit to find the next occurrence of a metadata block of a
              certain type.  Valid metadata types are: none (unused  metadata  clump  block),  sb
              (superblock),  rg  (resource group), rb (rg bitmap), di (disk inode aka dinode), in
              (indirect block list), lf (directory leaf), jd (journaled data),  lh  (journal  log
              header),  ld (journal log descriptor), ea (extended attribute), ed (ea data block),
              lb (log buffer), 13 (unused block type 13), qc (quota change).  The block AFTER the
              one  specified  with  -p is the starting point for the search.  For example, if you
              specify gfs2_edit -p rg 12 find rg /dev/your/device,  it  will  find  the  rg  that
              follows  rg 12 (normally, this would be rg 13).  Note, however, that since metadata
              often appears in the journals, it could be a copy  of  a  different  RG,  inside  a
              journal.   Also note that gfs2_edit will only find allocated metadata blocks unless
              the type specified is none, sb, rg or rb.  In other words, if you  try  to  find  a
              disk inode, it will only find an allocated dinode, not a deallocated one.

              Optionally,  you  may  specify the keyword field followed by a valid metadata field
              name.  Right now, only the fields in disk inodes and resource groups  are  allowed.
              If no value is specified after the field, the value of the field will be printed to
              stdout.  If a value is specified, the field's value will be changed.  This  may  be
              used,  for  example, to artificially change the di_size field for an inode in order
              to test fsck.gfs2's ability to detect and fix the problem.

       -s [structure | block]
              Specify a starting block for interactive mode.  Any  of  the  well-known  locations
              found  in  the  -p  option  may be specified.  If you want to start on a particular
              resource group, specify it in quotes, e.g. -s "rg 3"

       -h, -help, -usage
              Print help information.

       -c [0 | 1]
              Use alternate color scheme for interactive mode: 0=normal  (dark  colors  on  white
              background), or 1 (light colors on black background).

       -V     Print program version information only.

       -x     Print in hex mode.

       -z <0-9>
              Compress  metadata  with  gzip  compression  level  1  to 9 (default 9). 0 means no
              compression at all.

       rg <rg> <device>
              Print the contents of Resource Group <rg> on <device>.

              <rg> is a number from 0 to X - 1, where X is the number of RGs.

       rgcount <device>
              Print the number of Resource Groups in the file system on <device>.

       rgflags <rg> [new_value] <device>
              Print and/or modify the rg_flags value of Resource Group <rg> on <device>.

              <rg> is a number from 0 to X - 1, where X is the number of RGs.   If  new_value  is
              not  specified,  the  current  rg_flags value will be printed but not modified.  If
              new_value is specified, the rg_flags field will be overwritten with the new value.

       printsavedmeta <filename>
              Print off a list of blocks from  <filename>  that  were  saved  with  the  savemeta
              option.

       savemeta <device> <filename>
              Save  off  the  GFS2  metadata (not user data) for the file system on the specified
              device to a file given by <filename>.  You can use  this  option  to  analyze  file
              system  problems  without  revealing sensitive information that may be contained in
              the files.  This option works quickly by using the  system  bitmap  blocks  in  the
              resource  groups  to  determine  the  location  of  all  the metadata.  If there is
              corruption in the bitmaps, resource groups or rindex file, this method may fail and
              you  may  need  to use the savemetaslow option.  The destination file is compressed
              using gzip unless -z 0 is specified.

       savemetaslow <device> <filename>
              Save off GFS2 metadata, as with the savemeta option, examining every block  in  the
              file  system for metadata.  This option is less prone to failure due to file system
              corruption than the savemeta option, but it is  extremely  slow.   The  destination
              file is compressed using gzip unless -z 0 is specified.

       savergs <device> <filename>
              Save off only the GFS2 resource group metadata for the file system on the specified
              device to a file given by <filename>.  The destination  file  is  compressed  using
              gzip unless -z 0 is specified.

       restoremeta <filename> <dest device>
              Take  a  compressed  or  uncompressed  file  created  with  the savemeta option and
              restores its contents on top of the specified destination  device.   WARNING:  When
              you  use  this  option,  the  file system and all data on the destination device is
              destroyed.  Since only metadata (but no  data)  is  restored,  every  file  in  the
              resulting  file system is likely to be corrupt.  The ONLY purpose of this option is
              to examine and debug file system problems by restoring and examining the  state  of
              the saved metadata.  If the destination file system is the same size or larger than
              the source file system where the metadata was saved, the resulting file system will
              be  the  same  size  as  the source.  If the destination device is smaller than the
              source file system, gfs2_edit will restore as much as it can,  then  quit,  leaving
              you with a file system that probably will not mount, but from which you might still
              be able to figure out what is wrong with the source file system.

INTERACTIVE MODE

       If you specify a device on the gfs2_edit command line and you  specify  no  options  other
       than  -c, gfs2_edit will act as an interactive GFS2 file system editor for the file system
       you specify.  There are three display modes: hex mode, structure mode and  pointers  mode.
       You  use  the  m  key  to  switch between the modes, as described below.  The modes are as
       follows:

       Hex mode (default)
              Display or edit blocks of the file system in hexadecimal and ascii.

              Lines at the top indicate the currently displayed block in both  hex  and  decimal.
              If the block contains a GFS2 data structure, the name of that structure will appear
              in the upper right corner of the display.  If the block is a well-known block, such
              as the superblock or rindex, there will be a line to indicate what it is.

              In  hex  mode,  you  can  edit  blocks by pressing <enter> and entering hexadecimal
              digits to replace the highlighted hex digits.  Do  NOT  precede  the  numbers  with
              "0x".   For  example, if you want to change the value at offset 0x60 from a 0x12 to
              0xef, position your cursor to offset 0x60, so that  the  12  is  highlighted,  then
              press <enter> and type in "ef".  Press <escape> or <enter> to exit edit mode.

              In  hex  mode,  different  colors  indicate  different things.  For example, in the
              default color scheme, the GFS2 data structure will be black, data offsets  will  be
              light blue, and actual data (anything after the gfs2 data structure) will be red.

       Structure mode
              Decode the file system block into its GFS2 structure and display the values of that
              structure.  This mode is most useful for  jumping  around  the  file  system.   For
              example,  you  can  use the arrow keys to position down to a pointer and press J to
              jump to that block.

       Pointers mode
              Display any additional information appearing on the  block.   For  example,  if  an
              inode  has  block  pointers, this will display them and allow you to scroll through
              them.  You can also position to one of them and press J to jump to that block.

Interactive mode command keys:

       q or <esc>
              The q or <escape> keys are used to exit gfs2_edit.

       <arrow/movement keys> up, down, right, left, pg-up, pg-down, home, end
              The arrow keys are used to highlight an area of the display.  The J key may be used
              to jump to the block that is highlighted.

       m - Mode switch
              The  m  key is used to switch between the three display modes.  The initial mode is
              hex mode.  Pressing the m key once switches  to  structure  mode.   Pressing  it  a
              second  time  switches  from  structure mode to pointers mode.  Pressing it a third
              time takes you back to hex mode again.

       j - Jump to block
              The j key jumps to the block number that is currently highlighted.   In  hex  mode,
              hitting J will work when any byte of the pointer is highlighted.

       g - Goto block
              The  g key asks for a block number, then jumps there.  Note that in many cases, you
              can also arrow up so that the current  block  number  is  highlighted,  then  press
              <enter> to enter a block number to jump to.

       h - Help display
              The h key causes the interactive help display to be shown.

       e - Extended mode
              The e key causes gfs2_edit to switch to extended ("pointers") mode.

       c - Color scheme
              The c key causes gfs2_edit to switch to its alternate color scheme.

       f - Forward block
              The  f key causes you to scroll forward one block.  This does not affect the "jump"
              status.  In other words, if you use the f  key  to  move  forward  several  blocks,
              pressing <backspace> will not roll you back up.

       <enter> - Edit value
              The <enter> key causes you to go from display mode to edit mode.  If you are in hex
              mode and you hit enter, you can  type  new  hex  values  at  the  cursor's  current
              location.   Note:  pressing  <enter>  in  structure  mode allows you to enter a new
              value, with the following restrictions:  For gfs2 disk inodes and resource  groups,
              it  will  actually  change  the  value  on  disk. However, inode numbers may not be
              changed.  For all other structures, the values entered are ignored.

              If you use the up arrow key to highlight the block number, then press <enter>,  you
              may  then enter a new block number, or any of the well-known block locations listed
              above (e.g. sb, rindex, inum, rg 17, etc.) and gfs2_edit will  jump  to  the  block
              specified.  If you specify a slash character followed by a metadata type, gfs2_edit
              will search for the next occurrence of that metadata block type,  and  jump  there.
              It  will  take  you to block 0 if it does not find any more blocks of the specified
              metadata type.

       <home> If you are in pointers mode, this takes you back to the starts of the pointers  you
              are viewing.  Otherwise it takes you back to the superblock.

       <backspace>
              This takes you back to the block you were displaying before a jump.

       <space>
              This takes you forward to the block you were displaying when you hit <backspace>.

EXAMPLES

       gfs2_edit /dev/roth_vg/roth_lv
              Display and optionally edit the file system on /dev/roth_vg/roth_lv

       gfs2_edit -p sb /dev/vg0/lvol0
              Print the superblock of the gfs2 file system located on /dev/vg0/lvol0.

       gfs2_edit -p identify 2746 2748 /dev/sda2
              Print  out  what  kind  of  blocks  are  at  block  numbers 2746 and 2748 on device
              /dev/sda2.

       gfs2_edit -p rindex /dev/sda1
              Print the resource group index system file located on device /dev/sda1.

       gfs2_edit savemeta /dev/sda1 /tmp/our_fs
              Save off all metadata (but no user data) to file /tmp/our_fs.

       gfs2_edit -p root /dev/my_vg/my_lv
              Print the contents of the root directory in /dev/my_vg/my_lv.

       gfs2-edit -x -p 0x3f7a /dev/sda1
              Print the contents of block 16250 of /dev/sda1 in hex.

       gfs2_edit -p 12345 /dev/sdc2
              Print the gfs2 data structure at block 12345.

       gfs2_edit rgcount /dev/sdb1
              Print how many Resource Groups exist for /dev/sdb1.

       gfs2_edit -p rg 17 /dev/sdb1
              Print the contents of the eighteenth Resource Group on /dev/sdb1.

       gfs2_edit rgflags 3 /dev/sdb1
              Print the rg_flags value for the fourth Resource Group on /dev/sdb1.

       gfs2_edit rgflags 3 8 /dev/sdb1
              Set the GFS2_RGF_NOALLOC flag on for the fourth Resource Group on /dev/sdb1.

       gfs2_edit -p 25 blockalloc /dev/roth_vg/roth_lv
              Print the block allocation type of block 25.  May produce this output: 3 (Metadata)

       gfs2_edit -p 25 blockalloc 1 /dev/roth_vg/roth_lv
              Change the block allocation type of block 25 to data.  May produce this output: 1

       gfs2_edit -p 25 blocktype /dev/roth_vg/roth_lv
              Print the metadata block type of block 25.  May produce this output: 4 (Block 25 is
              type 4: Dinode)

       gfs2_edit -p 25 field di_size /dev/roth_vg/roth_lv
              Print the di_size field of block 25.  May produce this output: 134217728

       gfs2_edit -x -p 25 field di_size /dev/roth_vg/roth_lv
              Print  the  di_size  field  of  block 25, in hexidecimal.  May produce this output:
              0x8000000

       gfs2_edit -p 25 field di_size 0x4000 /dev/roth_vg/roth_lv
              Change the di_size field of block 25 to the hexidecimal value 0x4000.  May  produce
              this output: 16384

KNOWN BUGS

       The directory code does not work well.  It might be confused
              by directory "sentinel" entries.

                                                                                     gfs2_edit(8)