Home | Download | Documentation | Programming | FAQ | About Me
debugfs : An unique command

Hi,
I searched for an user guide on debugfs command (other than man page) but didn't find more documents about it :( So here is an doc for you,where i tried to explain some basics stuffs that can be performed with debugfs.

I Assume you are root user and know about ext2/ext3 File System terms like nova,supernova..oops sorry - i mean block,superblock,inode,group descriptors, bitmap. If not, please Check out http://web.mit.edu/tytso/www/linux/ext2intro.html You can also look into Gadi Oxmen's ext2ed project which provides good doc about ext2 internals. If you want an unreliable guide - [written by myself] then check out Kick Start with ext3 :-)

Ok.Before we begin few stuffs for you to set things clear and loud :-)

*Let me tell you one thing this is not a prefect user guide for debugfs by any means. I'm going to write this docs as i learn about debugfs. So if you mess up with your System - donot blame me - After all it's your system you got to take responsiblity for your actions - Be a Responsible Linux User:-)

*And also i adamantly refuse/reject any comments on my english. [Though I know it's very poor - i'm not interested in improving it. :-) as i prefer spending that time in improving my programming language skills]

Let's Jump into debugfs. What's debugfs? man page says "debugfs - ext2/ext3 file system debugger". Type debugfs on terminal it'll display something similar to below given output version and date [i guess it should be release date]

# debugfs
debugfs 1.37 (21-Mar-2005)
debugfs:
Which file system partition to explore? If you don't know about partitions peek into man df, by the time you looked into man page of df .. i opened sda5 in my system using
debugfs: open /dev/sda5
Now what to do this ?I got absoultely no idea.Let's seek some help using command
debugfs: help
It displays list of available options.Let me count it... one ..two..three....four........wow 51 options Don't get scared by it's number.It'll be easy if you are ready to learning it and it'll be very very easy if you are very much interested in learning :-) See already we know 3 options like open,help.yes. that's two not three.:-) Here we go for third one : quit.
debugfs: quit
but before we quit it's always better to close /dev/sda5 which we opened using 'open' so type
debugfs: close
It'll display a message 'File closed successfully.' [just kidding - it wont display any messge] try and repeat the same command
debugfs: close
close: Filesystem not open

Now we know there is nothing to close so type quit.Take some tea/coffee break - come back later :-) I'm also going outside for a little break.
ok.Back to debugfs.Now let's try and provide the partition name while invoking debugfs itself.
# debugfs /dev/sda5
Let's check that first option when we type help. (i.e)show_debugfs_params (or) params
debugfs: params
Open mode: read-only
Filesystem in use: /dev/sda5

Yes.we got the supplied arguments as result.Hey look here - there is an option called features[Set/print superblock features]let's see what's that really mean.
debugfs: features
Filesystem features: has_journal ext_attr resize_inode dir_index filetype needs_recovery sparse_super large_file

Yes.Just what i expected - It's ...It's ...features of File System :-) ok..ok..you got me ...i agree right now - i'm 10000% sure i got no idea about this result. :-) let's explore this later :-) ..Let's check 'dirty' option
debugfs: dirty
dirty: Filesystem opened read/only

hmmmm...how to open a file system as Read-Write using debugfs? so that we can check this command.Ya. got check syntax of 'open' option
open: Usage: open [-s superblock] [-b blocksize] [-c] [-w]
wondering how i got the syntax of open for debugfs.Just type :
debugfs: open
Please Forget to provide the device name so that it'll give you the syntax :-) so close it once and open with -w option like this:
debugfs: close
debugfs: open -w /dev/sda5

Seems like the file system is opened in write mode.How to verify that?let's try params options:
debugfs: params
Open mode: read-write

Yes.finally we opened the file system in write mode too :-)now try that 'dirty' option. If my guess is correct - dirty will set the file system as dirty so that on next boot file system check (fsck)will be performed.

i typed dirty once .
twice..
Do you want me to try for third time?
Ok .Here i go:
debugfs: dirty
debugfs: dirty
debugfs: dirty

Let's quit debugfs and restart the system to check im right or not [i have to save this file
and take a backup too-before reboot :-)]
No..I'm wrong - It didn't do any file system check (fsck) during reboot :( ....May be it should work with ext2 file system.I'm using ext3.So next option is:
'init_filesys' it says "Initalize a filesystem (DESTROYS DATA)" - I'm not going to run debugfs to try this option :-) A quick check on man page said "Creates an ext2 file system on the device".
Usage of this command is
initialize
You have to provide device name and it's default block size for creating new ext2FS.
Then comes 'show_super_stats' or simply 'stats'. When i typed stats i can see plenty of info. like,
Filesystem volume name: /opt
and
Last mounted on:
and
Filesystem UUID: cbd9db58-ce06-47e3-add0-5631faef0d37
and here goes magic signature of FS:
Filesystem magic number: 0xEF53
Filesystem revision #: 1 (dynamic)
clealy features of FS
Filesystem features: has_journal ext_attr resize_inode dir_index filetype needs_recovery sparse_super large_file
and
Default mount options: (none)
and we got state of FS,
Filesystem state: clean
wait...wait...this is what we tried earlier with 'dirty' option??? Let me type dirty again
debugfs: dirty
now run stats.
Filesystem state: not clean

Yes.Let reboot now and look for that fsck -I hope it works now - Keeping finger crossed :-)No again...didn't give the expected results.-It didn't run file system check at boot time. :-( i ran 'stats' it said state is 'clean' ???How it became clean now???I wonder while rebooting something resets this state.
Let me try for last time,run dirty and stats shows file system state as 'not clean'.Now i'll disconnect the power supply rather than rebooting or shutdown in proper way. Let's wait for it ......Yes.Looks like file system check performed while booting said "PASSED" But is that correct approach?Let me try to disconnect power without manually making FS dirty using debugfs.
YES.This time it didn't perform File system Check.So dirty forces file system check.I hope someone will help to understand more about this.[why ?? It doesn't perform file system check if i going to reboot and performs file system check if i disconnect power ???Any insights into this issue --ping me :-)]
Ok with this 'dirty' stuff....Where were we ?..yes digging about 'stats'.Run stats yourself and see FS setting like Inode count,Block count,Free blocks,Free Inodes,block size etc etc..And also note down at the end we have group descriptor informaions.Very Useful details to explore and explode your FS - Isn't it? ;-)
'ncheck' takes inode as an input and gives the path name.
debugfs: ncheck 2348010
Inode Pathname
2348010 /oss/man/cat1

Then we have 'icheck' when you provide block number as input it will tell you which inode it belongs to. First how to find correct block number ??? Try 'stat' option with file it'll display the inode info. Beware 'stat' will give a file inode details where as 'stats' will provide file system information that reside in super block.I guess 's' in stats refer to super block .
debugfs: stat ttt
Inode: 13 Type: regular Mode: 0644 Flags: 0x0 Generation: 1899498200
User: 0 Group: 0 Size: 11
File ACL: 1621061 Directory ACL: 0
Links: 1 Blockcount: 16
Fragment: Address: 0 Number: 0 Size: 0
ctime: 0x48050386 -- Wed Apr 16 01:05:34 2008
atime: 0x48050385 -- Wed Apr 16 01:05:33 2008
mtime: 0x48050386 -- Wed Apr 16 01:05:34 2008
BLOCKS:
(0):1515291
TOTAL: 1

stat gives inode details of given file like Inode number,file type,user,size,time,links andblocks..So we got a valid block 1515291 . Let's use this block number with icheck
debugfs: icheck 1515291
Block Inode number
1515291 13

Gives the expected inode number 13 of file 'ttt'.
No comments about following options :
chroot
cd
ls
ln
unlink
mkdir
rmdir
rm

What's that kill_file? Name itself creates curiosity.It dellocates the inode&block but doesn't remove the entry from directory structure.
$ls -il giis.txt
15 -rw-rw-r-- 1 oss oss 18 Apr 16 15:54 giis.txt
Now i used kill_file on giis.txt.
debugfs: kill_file giis.txt
Even now
$ls -il giis.txt
15 -rw-rw-r-- 1 oss oss 18 Apr 16 15:54 giis.txt

gives the same result.
debugfs: stat giis.txt
Inode: 15 Type: regular Mode: 0664 Flags: 0x0 Generation: 3139576194
User: 500 Group: 500 Size: 18
File ACL: 505359 Directory ACL: 0
Links: 1 Blockcount: 16
Fragment: Address: 0 Number: 0 Size: 0
ctime: 0x4805d3eb -- Wed Apr 16 15:54:43 2008
atime: 0x4805d3e7 -- Wed Apr 16 15:54:39 2008
mtime: 0x4805d3eb -- Wed Apr 16 15:54:43 2008
dtime: 0x4805d445 -- Wed Apr 16 15:56:13 2008
BLOCKS:
(0):10234
TOTAL: 1


By using kill_file giis.txt file's inode and block are marked as free.They can be used by some other file.You can verify that by checking with ffi and ffb options which provide next available free inode number and next available free block number.

debugfs: ffi
Free inode found: 15

debugfs: ffb
Free blocks found: 10234


Note inode & block number from ffi and ffb are same as stat result. I'm not sure what the purpose of kill_file.Any way quite interesting stuff.
clri says it'll clear inode contents.
debugfs: clri ttt

now stat ttt shows clean inode with timing date back to Thursday Jan 1 1970 exactly 5.30
And all other entries are set to 0 and finally the type set as 'bad type' :-)

Let's try the next option with debugfs - testi which says it'll Test an inode's in-use flag.In turn it means using testi you can tell whether an inode is allocated or free state.

debugfs: testi Laks
Inode 880417 is marked in use

Lets check the same for giis.txt for which kill_file option is implemented.
debugfs: testi giis.txt
Inode 15 is not in use

'seti' will mark the inode as in-use. (ie) It's not an free inode.Let's check the same with giis.txt
debugfs: seti giis.txt
Now let's verify that :
debugfs: testi giis.txt
Inode 15 is marked in use

Yes.Previously inode 15 marked as free -but now with the help of seti it's marked as in-use.Now we have 'freei' as name indicates it will set an inode as free.
debugfs: freei giis.txt
debugfs: testi giis.txt
Inode 15 is not in use

cool. You can just play with inode status.:-)
Similar to testi,seti,freei we got testb,setb,freeb with which we can mark a block as free / in-use.
Usage: testb [count]
To verify whehther block number 10234 is free or not.

debugfs: testb 10234
Block 10234 not in use

you can test more than one block with the help count . Let check 2 blocks starting from 10234

debugfs: testb 10234 2
Block 10234 not in use
Block 10235 marked in use


Then we have freeb and setb their usage is :
debugfs: setb
setb: Usage: setb [count]
debugfs: freeb
freeb: Usage: freeb [count]


I guess you know what this will do...setb and freeb are homework for you :-)

The mi option : mission impossible :-)
It's referred as modify_inode. yes it's really impossible task which can be achieved only with mi. With this you can modify inode contents of file. That's great - isn't it?
when i typed ,
debugfs: mi giis.txt
Mode [0100664]


and awaits for my input - i don't want to change mode.so just press enter then comes

User ID [500]
Group ID [500]
Size [18] 20
Creation time [1208341483]
Modification time [1208341483]
Access time [1208341479]
Deletion time [1208341573]
Link count [1]
Block count [16]
File flags [0x0]
Generation [0xbb222182]
File acl [505359]
High 32bits of size [0]
Fragment address [0]
Fragment number [0]
Fragment size [0]
Direct Block #0 [10234]
Direct Block #1 [0]
Direct Block #2 [0]
Direct Block #3 [0]
Direct Block #4 [0]
Direct Block #5 [0]
Direct Block #6 [0]
Direct Block #7 [0]
Direct Block #8 [0]
Direct Block #9 [0]
Direct Block #10 [0]
Direct Block #11 [0]
Indirect Block [0]
Double Indirect Block [0]
Triple Indirect Block [0]
debugfs:


Note that i entered the size field as 20 while acutal size is 18. That's really cool.you can see..data block number can also be set using this that's super-duper stuff.May be i'll play with this later.Remember anytime,anywhere its always dangeous to play with inode. :-) But if you are brave Linux user/programmer just ignore my warning and enjoy yourself :-)

expand option : man page said expand the directory.what's there to expand 'a directory' ?? Let me check this first creat a new directory called ext3crave and also creat a sample test file there. First take a backup current stat info of the directory ext3crave.

debugfs: stat ext3crave
Inode: 1926563 Type: directory Mode: 0775 Flags: 0x0 Generation: 3139576210
User: 500 Group: 500 Size: 4096
File ACL: 505359 Directory ACL: 0
Links: 2 Blockcount: 16
Fragment: Address: 0 Number: 0 Size: 0
ctime: 0x4806e498 -- Thu Apr 17 11:18:08 2008
atime: 0x4806e49e -- Thu Apr 17 11:18:14 2008
mtime: 0x4806e498 -- Thu Apr 17 11:18:08 2008
BLOCKS:
(0):1951197
TOTAL: 1


ok...now go for expand.

debugfs: expand ext3crave

No messages displayed :-(...what's happened?run stat and hope for some clue....
debugfs: stat ext3crave
Inode: 1926563 Type: directory Mode: 0775 Flags: 0x0 Generation: 3139576210
User: 500 Group: 500 Size: 8192
File ACL: 505359 Directory ACL: 0
Links: 2 Blockcount: 24
Fragment: Address: 0 Number: 0 Size: 0
ctime: 0x4806e498 -- Thu Apr 17 11:18:08 2008
atime: 0x4806e661 -- Thu Apr 17 11:25:45 2008
mtime: 0x4806e498 -- Thu Apr 17 11:18:08 2008
BLOCKS:
(0):1951197, (1):1951200
TOTAL: 2


wow....look the size is doubled along with block count and the total said 2.Let's quickly check the directory.

ls -il ext3crave

No..nothing special there. Look at stat carefully you can see 1951200 block added.My guess is - the directory structure normally has size of block size with 'expand' you can increase it's size.
debugfs: expand ext3crave
debugfs: stat ext3crave
Inode: 1926563 Type: directory Mode: 0775 Flags: 0x0 Generation: 3139576210
User: 500 Group: 500 Size: 12288
File ACL: 505359 Directory ACL: 0
Links: 2 Blockcount: 32
Fragment: Address: 0 Number: 0 Size: 0
ctime: 0x4806e498 -- Thu Apr 17 11:18:08 2008
atime: 0x4806e661 -- Thu Apr 17 11:25:45 2008
mtime: 0x4806e498 -- Thu Apr 17 11:18:08 2008
BLOCKS:
(0):1951197, (1-2):1951200-1951201
TOTAL: 3


see i tried expand again a new block 1951201 is added now.Now the directory size is
12288. ie. (4096+4096+4096) I'm trying to verify this increased size with ls -il but it shows only 4096
$ls -il ext3crave
1926563 drwxrwxr-x 2 oss oss 4096 Apr 17 11:18 ext3crave

---i don't know why???? But using debugfs stat ext3crave gives expected 12288 as size.
something wrong with ls command ????
Then use lsdel to list deleted inodes.
debugfs: lsdel
Inode Owner Mode Size Blocks Time deleted
15 500 100664 20 1/ 1 Wed Apr 16 15:56:13 2008
1 deleted inodes found.


I guess the blocks represent the total no.of data blocks released
while deleting this file. Next comes my favourite one - undelete :-)
undel: Usage: undelete
debugfs: undel 15 /opt/oss/heee
15: File not found by ext2_lookup


What i tried here is simple , we got the deleted inode number from lsdel. But it displayed error message.I believe this undelete will work only for ext2 but not with ext3.

'write' looks similar to cp command.

debugfs: write /opt/exthide.txt exthide2.txt
Allocated inode: 17

First , ls -il /opt gave me this
? ?--------- ? ? ? ? ? exthide2.txt

but after sometime i got :
17 -rw-rw-r-- 1 root root 21 Apr 17 12:11 exthide2.txt

is it because- inode is in buffer and took sometime to write to disk ??

dump or dump_inode
debugfs: dump giis.txt giis_inode.txt
dump writes the file content into an output file.
similar to cp command?i wonder am i missing something here?

Right...Keep reading we got very few commands left to explore. You already read 77.732454% of this document still got just 22.267546% to reach EOF :-) Keep going.... :-)

Next option 'rdump' - It copies a directory and it's contents to another location.
debugfs: rdump ext3crave /opt/extcrave
Now ext3crave copied to /opt/extcrave.Similar to cp -r command. Next option : set_super_value, ssv used to set value in superblock.use ssv -l to see list of superblock values which can be set.It's syntax is :
Usage: set_super_value
I wonder this is option will affect all superblock copies or applicable only to first superblock only?[i prefer not to play with superblock as of now - since i may lose this file :-) ]Similar to superblock we have sif-set inode field. Syntax is similar to ssv.
set_inode
changing...mayI'm trying to set the size to 100.but user id is changing...may be i'm using a older version of
debugfs.

debugfs: sif <17> size 100
debugfs: stat exthide2.txt
Inode: 17 Type: regular Mode: 0664 Flags: 0x0 Generation: 0
User: 100 Group: 0 Size: 0
File ACL: 0 Directory ACL: 0
Links: 1 Blockcount: 8
Fragment: Address: 0 Number: 0 Size: 0
ctime: 0x4806f111 -- Thu Apr 17 12:11:21 2008
atime: 0x4806f111 -- Thu Apr 17 12:11:21 2008
mtime: 0x4806f111 -- Thu Apr 17 12:11:21 2008
BLOCKS:
(0):1515007
TOTAL: 1


Remember we can set inode details with mi option too. But mi takes filename as input where as sif takes inode as input.Enough of sif. Next option in our queue is 'logdump'
debugfs: logdump
Journal starts at block 1, transaction 402979
Found expected sequence 402979, type 1 (descriptor block) at block 1
Found expected sequence 402979, type 2 (commit block) at block 3
Found expected sequence 402980, type 1 (descriptor block) at block 4
No magic number at block 66: end of journal.


Journaling informations.I'll learn about journal stuff and let you know about this soon .Till then Just remember you can view journal log data with logdump option.And then we have very simple options like 'htree','hash' Use a file with hash
debugfs: hash giis.txt
Hash of giis.txt is 0x444b98da (minor 0x0)


If you got any idea what's this mean - then mail me [i'm serious] :-)

dirsearch - Search a file within directory.
Usage: dirsearch dir filename
Should be easy one.try yourself.

'imap' interesting option which gives the location of specified file.
debugfs: imap giis.txt
Inode 15 is part of block group 0
located at block 1006, offset 0x0700

see..giis.txt has inode numbered 15 and it's part of block group 0 and at location 1006 which is inode bitmap block. Then careful while using 'dump_unused'.It Dumps unused blocks to screen -with messages like
debugfs: dump_unused

Unused block 1515083 contains non-zero data:
//garbage comes here.

It'll dump contents of all deleted files.Finally we have bmap.Help says "Calculate the logical->physical block mapping for an inode"
debugfs: bmap giis.txt 10234
0


Again i have no idea about bmap.

Congrats !!!!!You have successfully completed the course.!!! You will be awarded 1000000$....I'm not serious here -- just kidding ..so please don't mail me asking for 1000000$ :-) :-) :-)

To explore your system ,try debugfs in read mode...and to explode your System ,try the same inwrite mode :-)If you like this docs and got any questions or got any answers for my questions- you can mail me.

Powered by
Open Source Programmers