DFSee version 17.0 2022-10-22 (c) 1994-2022: Jan van Wijk =========================[ www.dfsee.com ]========================== _______________________________________________________________________________ C O N T E N T S: _______________________________________________________________________________ Command reference = overview of APFS specific commands Detailed description = description for every command Note: All generic commands can be found in DFSCMDS.TXT, for example: ALLOC, CHECK, CLONE, RESIZE, RECOVER, SAVETO, SCAN, WIPE _______________________________________________________________________________ C O M M A N D R E F E R E N C E: _______________________________________________________________________________ APFS specific commands Active filesystem : APFS, specific commands are: BL = Translate and display 'this' LSN as a block number BL block [cmd] = Translate specified block-number to LSN, display using 'cmd' CATS [id][name] = Search FS-tree for INO and optional file/folder name COLlissions = Find filename duplicates (HASH collisions) in APFS volume CP [index] = Refresh to latest or specified checkpoint (history) DESC [f [l]] = Describe object TYPE/SUBTYPE, and FS/XFIELD RECORD types DUMP [params] = Dump recognized APFS blocks to display, with some filtering FOLDER [dirIno] = Display Catalog directory data for specified folder INO nr LEAVES [params] = Display contents of various APFS filesystem tree leaf-nodes LEAF [id] = Determine NEXT-leaf ID for given/last leaf ID, 0 = FIRST SUPER = Display the selected container SUPERBLOCK structure VI [vol-index] = Select a volume from a list, or specified volume index VIRT o x [-c] = Find blocknr for objec/transaction ID, volume or container For an up-to-date list of commands, use the '?' command APFS specific sector types (see ??? command) 's' = APFS C-superblock 'B' = APFS Btree (root) 'N' = APFS generic node 'M' = APFS SpaceManager 'S' = Sp CAB lvl2 Index 'i' = Sp CIB lvl1 Index 'm' = Sp BitMap Block 'O' = Object Map Block 'c' = CheckPoint Map 'D' = Volume Superblock 'Y' = Container Reaper 'y' = Cont. Reaper List 'E' = EFIboot JumpStart 'F' = Fusion WrBk Cache 'f' = Fusion WrBk List 'x' = Encr RollingState 'z' = General Bitmap 'Z' = Gen BitMap List For an up-to-date list, use the '???" command _______________________________________________________________________________ D E T A I L E D D E S C R I P T I O N: _______________________________________________________________________________ BL = Translate and display 'this' LSN as a block nr Purpose: Display block value for the CURRENT sector 'this' Parameters: none Output: cluster value Remarks: APFS specific, and alias for the generic 'CL' command _______________________________________________________________________________ BL block [cmd] = Translate hex block number to hex LSN, display using cmd Purpose: Display sector for specified block in default or cmd format Parameters: block mandatory Block value 0 .. max-block cmd optional Command to use for displaying the sector Output: display of the sector Remarks: APFS specific, and alias for the generic 'CL' command _______________________________________________________________________________ CATS [id][name] = Search FS-tree for INO and optional file/folder name Purpose: Search FS-tree for fsID and optional file/folder name, display result Parameters: Id Primary key: Parent-INO for DIR; INO for other (attribute) records\n" Key Additional key value: Name for DIR or XATTR; sibling-ID for sibling link Without a Key, it will search for an INODE record for INO 'Id' Options: -r:N Select type of record to search, default INO, or DIR when a name is given 1=SMET 2=PXT 3=INO 4=XAT 5=LNK 6=DSTR 8=FXT 9=DIR 10=STAT 11=SNAP 12=LM Output: A single line with either the type and location of the record found, or an error message _______________________________________________________________________________ COLlissions = Find filename duplicates (HASH collisions) in APFS volume Purpose: Find any filename HASH value collisions in an APFS volume Parameters: none Options: -test:[mask] Ignore DIR, optional mask some HASH bits (default 0xffffff) -refresh- Do NOT synchronize to latest volume checkpoint automatically Output: A single line for each file/directory where the HASH-value for its name is the same as for another one (the previous one in the catalog tree) with progress info on the status bar and a summary displayed at the end. Remarks: The -test option is simply there to test the output format for this function, since actual hash collissions are extremely rare. (1 in 4 million, for names within a single directory) With '-test' identical names in DIFFERENT directories may cause a hit, resulting in thousands of them for a typical macOS APFS boot volume. _______________________________________________________________________________ CP [index] = Refresh to latest or specified checkpoint (history)", Purpose: Determine latest valid checkpoint, optional offset by checkpoint index Parameters: index Number of checkpoints to go BACK in history, default 0 Options: -O:s NO display of superblocks, no output (silent) -O:q Display superblocks in a compact format (quiet) -O:v Display superblocks with more detail (verbose) Output: Results of finding the checkpoint with related superblocks Remarks: The -O: verbodity options work with many APFS commands, to control the amount/detail of the displayed information Volumes that are MOUNTED when opened, have a tendency to change, resulting in the disk contents being inconsistent for a while. This happens more quickly when there are many changes, which is the case for the macOS boot volume for example. Due to the 'copy on write' nature of the APFS filesystem, the most changed objects like superblocks and FS-tree nodes will be relocated all the time (using virtual to physical mappings) resulting in the displayed (and cached) values in DFSee become obsolete/invalid, causing all kinds of display/analysis errors. For the macOS system volume this can happen in mere SECONDS! The 'CP' command synchronizes to the LATEST state on the disk, refreshing the virtual-to-physical mapping trees, usually resolving the inconcistencies that way. However, in some cases you may need to (re)locate the information you were looking at by starting again from the ROOT (restarting 'browse' for example) Several commands, like 'browse', 'folder' and 'leaves' will automatically execute a 'cp' command at certain intervals to reduce the risk of inconcistencies when working. That said, the only SAFE and RELIABLE way to analyse an APFS filesystem is to UNMOUNT the filesystem, making them STABLE. One way to achieve that (unmount the filesystems, keep the disk) is to use the DFSee menu (using the macOS version of DFSee): File -> Device and Volume management -> Unmount volumes from a disk -> ... select the disk with the APFS partition ... Make sure to select THAT disk, not the 'virtual' one created by macOS for each of the APFS partitions present. After that re-open the partition, or issue a manual 'cp' command. On (almost ?) all other operating systems, the APFS partition will not be mounted anyway, so it is safe to work that way. Also when creating an IMAGE (like a compressed IMZ) from an APFS partition, it is best to do that when it is UNMOUNTED or you will face the same problems when opeing the image for analysis ... _______________________________________________________________________________ DUMP [params] = Dump recognized and valid APFS blocks to display Purpose: Iterate over all disk-blocks and display the recognized types Parameters: * dump until end of partition, or key blocks # recognized blocks to dump, default 2000 start blocknumber to start dumping, default 0 types sector-types to be included, default all Options Various options are available to select certain types of blocks or records (when the blocks are tree nodes) -dir:P On tree/node objects, limit to parent-INO P (use on FS-Tree only) -r:N On tree/node objects, limit to record type N (use on Snap/FS-Tree) 1=SMET 2=PXT 3=INO 4=XAT 5=LNK 6=DSTR 8=FXT 9=DIR 10=STAT 11=SNAP 12=LM -header- Suppress display of header info, show blocknumber and contents only -list On tree/node objects, add each found (DIR) record to the sector-list -name:wildc On tree/node objects, display DIR/XATTR only if wildcard name match -node On tree/node objects, display NODEs only (tree) no LEAF (contents) -node- On tree/node objects, display LEAFs only (contents) no NODE (tree) -raw On tree/node objects, NO record interpretation, dump RAW key/value -tree[:st] Limit to blocks with (tree) subtype 'st' default is 14 for FS-Tree 14=FS-Tree 15=Extents-Tree 16=Snapshot-Tree 21=Fusion-Tree -X:Xid Limit to blocks with Xid same/smaller as given transaction-ID 'Xid' -x:subType Exclude blocks with object subtype given (list with 'desc') -x Exclude blocks with object subtype 9 (SpcMan Free-Queue) -y:subType Exclude blocks with object subtype given (list with 'desc') -y Exclude blocks with object subtype 11 (Object Map) -z:subType Exclude blocks with object subtype given (list with 'desc') -z Exclude blocks with object subtype 15 (Block-Extent-reference) For an exact and up-to-date list of options, use 'dump -?' Output: Formatted contents of most of the know block-types, or a brief HEX-dump for blocks that are valid, but not recognized. Remarks: When looking FS-tree (directory/Inode etc) information it will be MUCH faster to use the 'leaves' command instead, since that only searches the LEAF nodes in the catalog B-tree for the FS. _______________________________________________________________________________ DESC [f [l]] = Describe object TYPE/SUBTYPE, and FS/XFIELD RECORD types", Purpose: Parameters: first First numeric blocktype value to show the type description for last Last numeric blocktype value to show, default same as 'first' Output: Numbered lists of the Blocktypes (with associated selection character), Btree record types as used in the FS, extent and snapshot B-trees, and the types of 'Xfields' as used in Directory and Inode record types. Remarks: Without specified values, all defined types are listed, and the Btree FS/XFIELD RECORD types are listed with a short description as well The displayed output as of the 16.0 release of DFSee is: APFS block/object types/subtypes (see 'dump -?', 'leaves -?', 'find' and '???' commands) (sub) Type number : 1 = 0x0001 : Container Superblock 's' = Block/Sector selection char (sub) Type number : 2 = 0x0002 : Btree-Root 'B' = Block/Sector selection char (sub) Type number : 3 = 0x0003 : Btree-Node 'N' = Block/Sector selection char (sub) Type number : 4 = 0x0004 : Unknown block type! (sub) Type number : 5 = 0x0005 : Spacemanager 'M' = Block/Sector selection char (sub) Type number : 6 = 0x0006 : Spm CAB level2 Index 'S' = Block/Sector selection char (sub) Type number : 7 = 0x0007 : Spm CIB level1 Index 'i' = Block/Sector selection char (sub) Type number : 8 = 0x0008 : Spm Bitmap 'm' = Block/Sector selection char (sub) Type number : 9 = 0x0009 : Spm Free Queue (sub) Type number : 10 = 0x000A : Extent list (sub) Type number : 11 = 0x000B : Object Map 'O' = Block/Sector selection char (sub) Type number : 12 = 0x000C : CheckPoint Map 'c' = Block/Sector selection char (sub) Type number : 13 = 0x000D : Volume Superblock 'D' = Block/Sector selection char (sub) Type number : 14 = 0x000E : FS tree (sub) Type number : 15 = 0x000F : Block-Extent-ref (sub) Type number : 16 = 0x0010 : Snapshot meta tree (sub) Type number : 17 = 0x0011 : Reaper object 'Y' = Block/Sector selection char (sub) Type number : 18 = 0x0012 : Reaper list 'y' = Block/Sector selection char (sub) Type number : 19 = 0x0013 : Map Snapshot (sub) Type number : 20 = 0x0014 : EFI JumpStart, boot 'E' = Block/Sector selection char (sub) Type number : 21 = 0x0015 : Fusion Cached (sub) Type number : 22 = 0x0016 : Fusion WrBack Cache 'F' = Block/Sector selection char (sub) Type number : 23 = 0x0017 : Fusion WrBack List 'f' = Block/Sector selection char (sub) Type number : 24 = 0x0018 : Encr Rolling State 'x' = Block/Sector selection char (sub) Type number : 25 = 0x0019 : Gen Purpose Bitmap 'z' = Block/Sector selection char (sub) Type number : 26 = 0x001A : Gp Bitmap Tree Btree RECORD type : 1 = 0x0001 : SnapMeta Xfield type : 1 = 0x0001 : SnapshotID Btree RECORD type : 2 = 0x0002 : PhysExtent Xfield type : 2 = 0x0002 : DeltaTrOID Btree RECORD type : 3 = 0x0003 : Inode Xfield type : 3 = 0x0003 : DocumentID Btree RECORD type : 4 = 0x0004 : Xattr Xfield type : 4 = 0x0004 : FileName Btree RECORD type : 5 = 0x0005 : SiblingLnk Xfield type : 5 = 0x0005 : PrevFsize Btree RECORD type : 6 = 0x0006 : DstreamId Xfield type : 6 = 0x0006 : Reserved-6 Btree RECORD type : 7 = 0x0007 : CryptState Xfield type : 7 = 0x0007 : FinderInfo Btree RECORD type : 8 = 0x0008 : FileExtent Xfield type : 8 = 0x0008 : DataStream Btree RECORD type : 9 = 0x0009 : DirEntry Xfield type : 9 = 0x0009 : Reserved-9 Btree RECORD type : 10 = 0x000A : StatDirect Xfield type : 10 = 0x000A : DirStatKey Btree RECORD type : 11 = 0x000B : SnapName Xfield type : 11 = 0x000B : FsMnt-UUID Btree RECORD type : 12 = 0x000C : MapSibling Xfield type : 12 = 0x000C : Reserved-C Xfield type : 13 = 0x000D : SparsBytes Xfield type : 14 = 0x000E : Rdevice-ID _______________________________________________________________________________ FOLDER [dirIno] = Display Catalog directory data for specified folder INO nr", Purpose: Display the contents of a folder (directory) in a DFSee 'DIR' format Parameters: dirIno Inode number of the folder/directory to show Options: -l- Do NOT create a new sector list from the folder contents Output: A table like display of directory entries, with two lines per listed file, subdirectory or symlink, in alternating colors Remarks: Each entry is identified by a .NNNN number at the start of the line, represeting the index in the sector-list, and mofe detailed infomation about that entry can be displayed using a command like '.2' to show info on entry '.000002' _______________________________________________________________________________ LEAVES [params] = Display contents of various APFS filesystem tree leaf-nodes", Purpose: Display contents of APFS filesystem trees (leafs) , with some filtering Parameters: * display until the last tree LEAF node is reached, or key leafs # recognized LEAF nodes to display, default 2000 start Leaf ID to start display, default 0 Options: -refresh- Do NOT synchronize to the latest volume checkpoint automatically -debug Only list the LEAF (virtual) node ID values, no contents display\n -dir:P On tree/node objects, limit to parent-INO P (use on FS-Tree only) -r:N On tree/node objects, limit to record type N (use on Snap/FS-Tree) 1=SMET 2=PXT 3=INO 4=XAT 5=LNK 6=DSTR 8=FXT 9=DIR 10=STAT 11=SNAP 12=LM -header- Suppress display of header info, show blocknumber and contents only -list On tree/node objects, add each found (DIR) record to the sector-list -name:wildc On tree/node objects, display DIR/XATTR only if wildcard name match -raw On tree/node objects, NO record interpretation, dump RAW key/value -tree[:st] Use prepared LEAF-cache for selected tree, default is 14 for FS-Tree 14=FS-Tree 15=Extents-Tree 16=Snapshot-Tree -X:Xid Limit to blocks with Xid same/smaller as given transaction-ID 'Xid' -x:subType Exclude blocks with object subtype given (list with 'desc') -x Exclude blocks with object subtype 9 (SpcMan Free-Queue) -y:subType Exclude blocks with object subtype given (list with 'desc') -y Exclude blocks with object subtype 11 (Object Map) -z:subType Exclude blocks with object subtype given (list with 'desc') -z Exclude blocks with object subtype 15 (Block-Extent-reference) Output: One or two lines per record found/matching, formatted to show the most relevant information in that record Remarks: The records as displayed in the sequence of 'leaf' nodes is determined by the primary/secondary key values, which are either the PARENT-INODE (for DIR-RECORDS) or the INODE (for most others) and the record type. For some record types there is a tertiary key value, for example the filename for DIR-RECORDS or the fileoffset for File-extent records. _______________________________________________________________________________ LEAF [id] = Determine NEXT-leaf ID for given/last leaf ID, and display leaf Purpose: Display the NEXT (in filesystem Btree-ordering) LEAF node contents Parameters: leaf Id LEAF node ID to find/display (virtual or physical block-number) when not specified, will find the NEXT LEAF node in the tree Leaf-ID 0 will result in displaying the FIRST leaf in the tree. Options: -tree[:st] Use prepared LEAF-cache for selected tree, default is 14 for FS-Tree 14=FS-Tree 15=Extents-Tree 16=Snapshot-Tree Output: One or two lines per record found/matching, formatted to show the most relevant information in that record Remarks: In addition to the specific '-tree' option, many of the selection or formatting options of the 'dump' and 'leaves' command also work with the 'leaf' command When starting with a 'leaf 0' command, and repeating just 'leaf' after that, the output will be very similar to the 'leaves' command that iterates over all known tree LEAF records. _______________________________________________________________________________ SUPER = Display the filesystem SUPERBLOCK sector Purpose: Display the contents of the APFS container superblock Parameters: none Output: Dirty status and sone other container level details _______________________________________________________________________________ VI [vol-index] = Select a volume from a list, or specified volume index", Purpose: Select a Volume to be used, with its associated directory-tree Parameters: index Volume index, 0 .. N (see 'super' display) Options: -O:s NO display of superblocks, no output (silent) -O:q Display superblocks in a compact format (quiet) -O:v Display superblocks with more detail (verbose) Output: Filesystem/superblock information, depening on verbosity Remarks: And APFS container CAN contain multiple volumes, each with its own directory/file tree, but SHARING the same freespace blocks with the other volumes in the same container. A typical macOS bootdrive (Mojave) contains 4 volumes in its system APFS container partition. When opening a container (partition) the FIRST volume will be selected automatically, for the macOS system partition that is the regular user partition (called 'Macintosh HD') _______________________________________________________________________________ VIRT o x [-c] = Find blocknr for objec/transaction ID, volume or container", Purpose: Find Object/Transaction-ID pair, in Volume/Container Object-Map, and display Parameters: oid Virtual Object-ID to find, from superblocks and related structures xid Transaction-ID to match (max), matches ANY Xid when not specified Options: -c Search in overall CONTAINER Object-Map, not the selected-VOLUME one -O:q Display object in a compact format, using less lines (quiet) -O:v Display object with more detail, using more lines (verbose) Output: A display of the resulting block/sector, in the format suitable for that kind of block, or an error message when the supplied 'oid' value does not represent a virtal object. _______________________________________________________________________________