DEBUGVMFS(8)

📦
version 0.2.5 · 5 versions
, in ubuntu noble, ubuntu questing

💖 DEBUGVMFS 💖

okay bestie, buckle up — this is the debugvmfs page from vmfs-tools, section 8 of the manual (the big-girl admin section, yes ma'am). it's a whole debugger for VMFS file systems and it is lowkey iconic. let's get into it 💅

🌸 NAME 🌸

debugvmfs — the VMFS file system debugger. that's the whole name section, short and stunning, no notes 💖

🦋 SYNOPSIS 🦋

debugvmfs VOLUME... COMMAND [ OPTIONS ]

✨ DESCRIPTION ✨

so debugvmfs is your little backstage pass: it lets you display all kinds of info about VMFS file systems, and it also lets you get at the data inside them. main character energy fr.

the VOLUME you open can be either a block device</> or an image file</> — either one, she's flexible 💁‍♀️ and when a VMFS is spread across several extents? bestie, you gotta hand over all the extents. every single one. no skipping, no crumbs.

heads up: most of these commands are still likely to change in future versions. so like, don't get too attached, iykyk 🫠

🎀 SPECIFYING FILES 🎀

some commands want a filespec as an argument, and a filespec can take either of these forms:

  • a path name — relative to the root of the filesystem if it starts with /, or relative to the current working directory otherwise (that second one is interactive mode only).
  • an inode number, wrapped up in angle brackets, e.g. '<4>' or '<0x1400004>' — adorable, right? 🎀

👑 COMMANDS 👑

every command, all of them, here we go, no crumbs left behind ✨

cat filespec [ ... ]

outputs the content of the given files from the VMFS. basically the cat you know and love, but make it VMFS 🐱

ls [ -l ] filespec

lists the files sitting at the given location within the VMFS.

with -l it gives you some more info, much like the output from ls(1) when you hand it the -l option. classic.

truncate filespec length

truncate the file to the specified length. R/W support must be enabled.

chmod filespec mode

change file permissions to the given mode. permissions era 💅

df

outputs information about file system size. the df of it all 🌈

get_file_block filespec position

get the file block corresponding to position in the specified file.

check_vol_bitmaps

checks volume bitmaps consistency. a lil vibe check for your bitmaps 🧚

show_heartbeats

outputs the active heartbeats on the file system. literally heartbeats 💓

read_block block_id [ ... ]

outputs the content within the specified block_id in binary.

get_block_status block_id

get the status — allocated or free — of the specified block_id.

alloc_block_fixed block_id

allocate the specified block_id. R/W support must be enabled.

alloc_block block_type

allocate a block of the specified type. R/W support must be enabled.

the allowed block types are: 1 (File Block), 2 (Sub-Block), 3 (Pointer Block) and 4 (File Descriptor / Inode). know them, love them, memorize them 📝

free_block block_id

free the specified block_id. R/W support must be enabled.

⚠️ Warning: can cause damage since no heartbeat is used at this time and a block used by a file can be freed. bestie, this one bites. be careful fr fr 💀

show

display value(s) of the given variable. check the VARIABLES section for the details. when no variable is given, it lists the top-level properties. a little sampler platter 🍓

shell

starts an interactive session. all of the above commands can be executed from within the interactive session — the whole lineup, live and in person 👑

the current working directory can be changed with the cd command, followed by a filespec.

the following output redirections are supported within the shell:

  • cmd > output — puts the output of cmd in the output file.
  • cmd >> output — appends the output of cmd to the output file.
  • cmd | external command — sends the output of cmd to the input of external command. and the external command itself can contain output redirection. layers, we love layers 🧅

examples:

  • read_block 0x00000681 | less
  • cat /.fdc.sf | hexdump -C
  • cat /.fdc.sf | hexdump -C > /tmp/fdc.hex
  • cat /.fdc.sf | hexdump -C | less

🌈 VARIABLES 🌈

variables in debugvmfs represent structures on the filesystem. the currently supported top-level variables are the following:

  • vol_version
  • version
  • label
  • mode
  • uuid
  • ctime
  • block_size
  • subblock_size
  • fdc_header_size
  • fdc_bitmap_count
  • fbb
  • fdc
  • pbc
  • sbc
  • fs
  • lvm
  • blkid[blk]
  • dirent["path"]
  • inode["filespec"]

the vol_version, version, label, mode, uuid, ctime, block_size, subblock_size, fdc_header_size, and fdc_bitmap_count properties are low-level information about the filesystem.

the fbb, fdc, pbc and sbc variables are bitmaps. running them through the show command will display all the bitmaps header fields. each of these fields can also be displayed individually:

  • bitmap.items_per_bitmap_entry
  • bitmap.bmp_entries_per_area
  • bitmap.hdr_size
  • bitmap.data_size
  • bitmap.area_size
  • bitmap.area_count
  • bitmap.total_items
  • bitmap.used_items
  • bitmap.free_items
  • bitmap.entry[n]

e.g. to display the data size of the fdc bitmap, type show fdc.data_size.

each bitmap.entry[n] (where 0 ≤ n < bitmap.bmp_entries_per_area * bitmap.area_count) contains information about each entry in the bitmap. the available fields are:

  • bitmap.entry[n].id
  • bitmap.entry[n].total
  • bitmap.entry[n].free
  • bitmap.entry[n].ffree
  • bitmap.entry[n].mdh
  • bitmap.entry[n].item[m]

the bitmap.entry[n].mdh is a metadata header. see further below for more details about metadata headers.

each bitmap.entry[n].item[m] (where 0 ≤ m < bitmap.items_per_bitmap_entry) contains information about a given item in the given entry. the available fields are:

  • bitmap.entry[n].item[m].used
  • bitmap.entry[n].item[m].dump

the pbc bitmap has an additional field:

  • pbc.entry[n].item[m].blocks

the lvm variable contains low-level information about the physical and logical volumes. the available fields are:

  • lvm.uuid
  • lvm.size
  • lvm.blocks
  • lvm.num_extents
  • lvm.extent[n]

each lvm.extent[n] (where 0 ≤ n < lvm.num_extents) contains low-level information about the physical volumes. the available fields are:

  • lvm.extent[n].device
  • lvm.extent[n].uuid
  • lvm.extent[n].lun
  • lvm.extent[n].version
  • lvm.extent[n].name
  • lvm.extent[n].size
  • lvm.extent[n].num_segments
  • lvm.extent[n].first_segment
  • lvm.extent[n].last_segment

each blkid[blk] (where blk is a block id) contains information on the given block id. the available fields are:

  • blkid[blk].item
  • blkid[blk].flags

each dirent[path] (where path is a path relative to the current directory in the shell or / outside the shell) contains information on the directory entry corresponding to the given path. the available fields are:

  • dirent["path"].type
  • dirent["path"].block_id
  • dirent["path"].record_id
  • dirent["path"].name

each inode[filespec] contains information on the inode corresponding to the given filespec. the available fields are:

  • inode["filespec"].id
  • inode["filespec"].id2
  • inode["filespec"].nlink
  • inode["filespec"].type
  • inode["filespec"].flags
  • inode["filespec"].size
  • inode["filespec"].blk_size
  • inode["filespec"].blk_count
  • inode["filespec"].uid
  • inode["filespec"].gid
  • inode["filespec"].mode
  • inode["filespec"].zla
  • inode["filespec"].tbz
  • inode["filespec"].cow
  • inode["filespec"].atime
  • inode["filespec"].mtime
  • inode["filespec"].ctime
  • inode["filespec"].rdm_id
  • inode["filespec"].mdh
  • inode["filespec"].blocks

Metadata headers are being used in several places, such as bitmap.entry[n].mdh and inode["filespec"].mdh. they mostly contain information about clustered accesses to metadata on the filesystem. the available fields are:

  • mdh.magic
  • mdh.pos
  • mdh.hb_pos
  • mdh.hb_lock
  • mdh.hb_uuid
  • mdh.hb_seq
  • mdh.obj_seq
  • mdh.mtime

variable values can also be used in expressions using square brackets, to use the variable value as an index. for example:

  • blkid[inode["filespec"].id]

enclosing a variable name with parentheses will use that variable value as a variable name. for example:

  • (blkid[blk].item).status

💜 AUTHORS 💜

Christophe Fillot <cf@utc.fr>, Mike Hommey <mh@glandium.org> — legends, honestly 🫶

🍓 SEE ALSO 🍓

vmfs-fuse(8)

💀 NOTES 💀

  1. cf@utc.fr — mailto:cf@utc.fr
  2. mh@glandium.org — mailto:mh@glandium.org

and that's a wrap, bestie 💖 this whole page is from version 0.2.5-patched, dated 04/01/2024 — go debug something, you absolute icon, and remember: read the warnings before you free_block anything 😭👑✨

📦 where this page comes from