gfs2_edit(8)

💖 gfs2_edit 💖

okay so bestie, welcome to the gfs2_edit(8) page from the System Manager's Manual — yes it's a whole manual page, yes it's long, and yes we're getting through all of it together. grab a snack 🍓

---

✨ NAME ✨

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

no cap, that's the whole vibe: it shows you the guts, or it messes with them. 🙈

---

🦋 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. It can also be run interactively, which is a whole thing — that's 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. like, great care great care. we are not playing. 💀

---

👑 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. two for one, we love a multitasker 💅

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. 😭 (yes you're literally breaking it on purpose. for science.)

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. your lil safety net 🫶
• -c [0 | 1] — Use alternate color scheme for interactive mode: 0=normal (dark colors on white background), or 1 (light colors on black background). aesthetic matters!! 🎀
• -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.gz> — Print off a list of blocks from <filename.gz> that were saved with the savemeta option.
• savemeta <device> <filename.gz> — 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.gz> — 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.gz> — 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.

like… that warning is giving "do not pass go" energy and it is NOT kidding. read it twice. 💀

💅 INTERACTIVE MODE 💅

okay bestie, here's the fun part. If you run gfs2_edit with a device on the command line and you give it no options other than -c, it turns into a full-on interactive GFS2 file system editor for the file system you picked. main character energy fr. ✨

There are three display modes: hex mode, structure mode, and pointers mode. You flip between them with the m key, and here's the tea on each one:

🧚 Hex mode (default) 🧚

Displays — or edits — blocks of the file system in hexadecimal and ascii. 💖

• Lines at the top tell you the currently displayed block in both hex and decimal.
• If the block holds a GFS2 data structure, the name of that structure pops up in the upper right corner of the display.
• If the block is a well-known block, like the superblock or rindex, there'll be a line telling you what it is. 👑

Editing time, babes: in hex mode you edit blocks by pressing <enter> and typing hexadecimal digits to replace the highlighted hex digits. Do NOT put "0x" in front of the numbers. For example, if you wanna change the value at offset 0x60 from a 0x12 to 0xef, position your cursor to offset 0x60 so the 12 is highlighted, then press <enter> and type in ef. Press <escape> or <enter> to dip out of edit mode. 🫶

And the colors? In hex mode, different colors mean different things. In the default color scheme: the GFS2 data structure is black, data offsets are light blue, and actual data (anything after the gfs2 data structure) is red. aesthetic 💅

🌸 Structure mode 🌸

This one decodes the file system block into its GFS2 structure and shows you the values of that structure. It's most useful for jumping around the file system — like, you can use the arrow keys to position down to a pointer and press J to jump straight to that block. slay. ✨

🦋 Pointers mode 🦋

Displays any extra info hanging out on the block. For example, if an inode has block pointers, this shows them and lets you scroll through them. You can also position to one of them and press J to jump to that block. iconic. 🎀

---

🎀 Interactive mode command keys: 🎀

• q or <esc> — the q or <escape> keys are how you exit gfs2_edit. bye bestie 👋
• <arrow/movement keys> up, down, right, left, pg-up, pg-down, home, end — the arrow keys highlight an area of the display. The J key can then jump to the block that's highlighted. 🏃‍♀️
• m - Mode switch — the m key flips between the three display modes. The initial mode is hex mode. Press m once → structure mode. Press it a second time → pointers mode. Press it a third time → back to hex mode again. round and round we go 💫
• j - Jump to block — the j key jumps to the block number that's currently highlighted. In hex mode, hitting J works 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 the current block number is highlighted, then press <enter> to enter a block number to jump to. 🚀
• h - Help display — the h key brings up the interactive help display. help a girl out 🙈
• e - Extended mode — the e key makes gfs2_edit switch to extended ("pointers") mode.
• c - Color scheme — the c key makes gfs2_edit switch to its alternate color scheme. new aesthetic unlocked 🌈
• f - Forward block — the f key scrolls you forward one block. This does not affect the "jump" status. In other words, if you use f to move forward several blocks, pressing <backspace> will not roll you back up. no takebacks 💀
• <enter> - Edit value — the <enter> key takes you from display mode into edit mode. If you're 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 lets you enter a new value, but with these 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 can 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'll take you to block 0 if it doesn't find any more blocks of the specified metadata type. 🧭
• <home> — if you're in pointers mode, this takes you back to the start of the pointers you're 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 ✨

get you a manpage that shows receipts, periodt. here's every single one:

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.gz Save off all metadata (but no user data) to file /tmp/our_fs.gz

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 hexadecimal. 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 hexadecimal value 0x4000. May produce this output: 16384

---

💀 KNOWN BUGS 💀

ok so not everything is slay:

• The directory code does not work well. It might get confused by directory "sentinel" entries. 😭

fr fr, be careful in there — the directory code is lowkey a mess.

---

and that's the whole page, bestie! this was the gfs2_edit(8) manual page — part two of two — so if you ever need to remember it, just know the page is literally called gfs2_edit(8). go forth and edit those blocks responsibly. 🫶✨💖