pinc Software
 

 BFS-tools 0.7.6 (May 25th, 2004)

Copyright ©2001-2004 pinc Software. All Rights Reserved


Introduction

 

This is a collection of some command line BFS tools. Most programs are currently non-destructive - for example, that means that you can't repair an unmountable volume, but you may be able to copy all files left to another disk.

The following tools are included:

  • bfsinfo you can use this program to get some information about the underlying structure of your BFS disk.
  • bfswhich can tell you which file covers the specified location.
  • chkindex can be used to check the integrity and validity of the indices on your BFS disk.
  • recover is the most complex program of the collection - it can be used to recover data on corrupt BFS disks which you can't even mount.
  • copy_to_bfs_image is currently the only destructive tool. It allows you to copy files to BFS volumes that are not mounted; don't mind, it really has a useful purpose.

I began writing the recover tool because I really needed such a tool - I had a defective memory stick in my computer, which rarely produced crashes, but even a memory test program couldn't find any faults (don't trust the c't ram checker - it's probably to slow to be able to trigger such errors).

Since I played around with some betas at that time, I didn't realize it at first, but after one of these crashes, I couldn't boot into BeOS anymore. After having booted from a CD, I was confrontated with 3 unmountable BFS partitions on two different harddisks - needless to say, that I used to backup the files on the other harddisk first; my latest CD backup was some month old.

Luckily, I had bought a copy of "Practical File System Design With The Be File System" written by BFS creator Dominic Giampaolo himself a couple of weeks before (it has been published by Morgan & Kaufmann. So I backed out from the real world for some time, sitting in front of my other computer, and wrote an early version of recover which repaired my backup & mp3 partition, and recovered almost all files from my main partition some time later - I never doubted that I could recover my data (that was a bit naïve, yes), but since there were several 1,000 blocks overwritten with some strange pattern, I had much luck that I didn't lose anything really important (just some mail and the latest version of BeMail, which I found as a gcc temp file on the disk some time later :-).

You may wonder why I have disabled the repair capabilities from recover; it's just not that mature, that you could just run that program to fix every disk out there - the drawback is that you need some space to recover your data; I needed to kill my QNX, and Linux partitions for this. But I know people; they would first try the desctructive way, and if that couldn't help, they would just try to recover their files - which may work not that good anymore, because of the failed repair process earlier. But with the upcoming releases I will also include really destructive programs, too, for your convenience.

Enough of boring stories, the following is a description of the tools I extracted from the codebase. At some point in the future, you may also find some GUI applications here, but not now, I am sorry.


bfsinfo

Synopsis: bfsinfo [-srib] device [allocation_group start]

Description: With bfsinfo you can have a look at the underlaying data structures in your BFS disk.
You can dump the disk's super block which holds some general information about the disk (its size, etc.), every i-node you know the location of, and the B+Tree that holds the directory and indices data.

Options:

  • -s dumps the whole super block structure, instead of just some info
  • -r dumps the disk's root inode structure
  • -i dumps an arbitrary inode structure - this needs the allocation group and start parameters
  • -b dumps the whole B+Tree of a directory, this also needs the allocation group and start parameters. Note that not every node of the tree can be dumped nicely, so it's just normal that there are some strange looking ones in there

Examples:

To get general idea about a disk:

> bfsinfo /dev/disk/ide/ata/0/master/0/0_1
Then you know that the root directory is at (8,0), and you want to dump its contents:
> bfsinfo -ib /dev/disk/ide/ata/0/master/0/0_1 8 0
8,0 would also be accepted, or even
> bfsinfo -ib /boot 524288
if the block run (8,0) is on that block on your boot disk.

Note: you can insert the real path to your partition or image file, the mount point (i.e. /boot/) to specify a particular disk. You can use the df command to learn which device serves which disk where.


bfswhich

Synopsis: bfswhich device allocation_group start

Description: bfswhich scans all files on disk and can tell you which is covering the block you specified in the arguments.
Note, scanning the whole disk takes some time. For example, you can use this tool in combination with chkbfs to find out which files claiming the same space on disk (if that error has been reported).

Options:

  • none

Examples:

To find out which file covers the block 1234567 on your boot disk:

> bfswhich /boot 1234567
To specify the block or block run, you have the same possibilities as the bfsinfo command provides.


chkindex

Synopsis: chkindex [-ifa] [index_name]

Description: With chkindex you can validate the indices on your disk and check if they are covering all the files they should.
It will check if the B+Tree structure itself is okay or not, if there are any files in the index that don't exist anymore on disk (which happens sometimes, but that doesn't harm your system in any way - and those files won't even be visible from a query).
Furthermore, it will check if the index has the complete file table indexed, and it will print out every file that's missing - this check can take a lot of time. To add missing files to an index, you can use the reindex tool, which is available separately, and for free.
It's usage is not like the other tools, but it's more or less the same as the mkindex, lsindex commands that are part of BeOS.

Options:

  • -i disables to check for non-existing files in the index
  • -f do not check if all the files are in the index
  • -a check all indices on disk - when you are specifying that option, you don't need the index_name parameter anymore. Note that this check can be really slow, depending on how many files are on the partition and how many files are in the different indices.

Examples:

First, we have to change the directory to one which is on the disk we want to operate on:

> cd /mp3s/
> chkindex Audio:Artist
The last call will perform a full check of that index, which will probably take some minutes. However, the following call will need much more time:
> chkindex -a
This will perform a full check on all indices on that disk. The output of


recover

Synopsis: recover [-id] [-r [start_offset] [end_offset]] device [recover_target_path]

Description: The device parameter is the most important one: that's the defective BFS partition where you want to recover files from, it doesn't even have to be a real device, it can also be an image file.
The program will first try to recreate the disk's super block if necessary, to be able to work with that disk. After this, it will scan the whole disk (even the log area) for inodes which are all collected.
Then, the whole disk structure will be checked and rebuilt when required. It will try to recreate missing anchors, and it is so smart to look if any of them were mirrored the log area, and it will scan through the name index to be able to determine the name for every file, as many as possible.
If you have selected a recover_target_path it will recreate the disk structure under that path, and will copy all files including their attributes to that target.

Options:

  • -i recreate all indices on target disk
  • -d dump missing and recreated i-node structures
  • -r operates on the raw disk - the whole disk will be scanned for BFS disks first, you will then be able to choose one of those. If you know approximately where your partition has been on disk, you can use the start_offset and end_offset parameters which define the range that will be scanned in bytes.
    Note, this option needs much time to scan the disk.

Examples: The following command will copy all files of "Broken-System.image" under /boot/home/recovered/:

> recover Broken-System.image /boot/home/recovered
If there is a directory "home" in the root of the image file, and it can be recovered, then it will be created in /boot/home/recovered/home.


copy_to_bfs_image

Synopsis: copy_to_bfs_image [-p] source_files [...] target_path

Description: This command allows you to copy files to an unmounted disk image. The image must not only be not mounted, you also have to make sure that all caches have been written back. It can be used to work around the BeOS cache consistency problem for image files; i.e. if you are needing files on a BFS image to work with them in an application like Bochs, you can use it to copy your files, and you won't need to reboot in order to have a consistent image.

If you have the partition on disk, there is no need to use this tool and you can safely mount the partition to copy the files.

Options:

  • -p The target path will be created if necessary

Examples: Copy a new boot loader to a BFS image called "openbeos.image":

> copy_to_bfs_image openbeos.image zbeos beos/system/
If the path "beos/system" doesn't yet exist on the image, you should use the -p option in order to create it automatically.


Tips & Tricks

Specifying the Volume to work on

As written above, almost all tools allow you to specify the volume in different ways, for example:

> bfsinfo /dev/disk/ide/ata/0/master/0/0_1
(by device name)
> bfsinfo /boot
(by mount point)
> bfsinfo bfs.image
(by path to an image)
Any exceptions are part of the documentation of the tool in question. recover also allows you to work on raw disks, while copy_to_bfs_image only supports image files.

If you are issuing any of the above commands on mounted volumes, you should make sure that all caches have been written back to the device, or they may not be able to work correctly. Issuing a sync command should do for real on-disk partitions.

List of Devices

To get a list of the devices of all mounted volumes, you can issue the df command:

> df
Mount            Type     Total    Free     Flags   Device
---------------- -------- -------- -------- ------- --------------------------
/                rootfs          0        0 ------W
/dev             devfs           0        0 ------W
/pipe            pipefs          0        0 ------W
/boot            bfs      10490444  1387620 QAM-P-W /dev/disk/ide/ata/0/master/0/0_1
/video           bfs      48933990  9463226 QAM-P-W /dev/disk/ide/ata/0/master/0/0_3
/audio           bfs      62918572 11204642 QAM-P-W /dev/disk/ide/ata/0/slave/0/0_1
Note, you will only see the mounted volumes using this command, and your output of df will likely differ. To work on one of these partitions, you can specify their mount point (i.e. /audio) or the device they are on.

Which device/partition?

If you need to access disks that are currently not mounted, or cannot be mounted anymore, you normally need to provide a path like /dev/disk/ide/ata/0/master/0/0_1 to the command you're interested in working on the disk (if it's a real disk and not only a disk image). That path determines how and where the hard drive is connected to your computer (ide/ata/0/master/0 means something like: primary IDE controller, hard disk jumpered as master (or even cable select)). In that directory, the whole disk will be exported as raw, while the partitions will be enumerated (0_1, 0_2, ...).

Partition is not there?

Unfortunately, BeOS will normally not publish the partitions of unmounted volumes in the device tree. However, you can force it to do that by issuing the following command:

> mountvolume -publishall
If the partition is still not visible in the correct directory (or no partition at all), it's likely that the partition table has been messed up. That could even mean good news, though, as your partition might be completely okay - but recovering it might be more difficult. You can use the raw option of recover to detect all BFS partitions on the disk.

In this case, if you have a spare hard drive, you might want to try to create a partition big enough to hold your affected BFS partition, and copy it over using the dd command like this:

> dd if=[old-partition] of=[new-partition] bs=1M count=[size of the partition in MB]
Also helpful is the option seek=[block] to start at the block your partition starts on the disk - you might have to use a block size of 512 (as in bs=512) to get to the correct location, though. Don't forget to multiply the argument to the count option based on the block size as well in that case.


Known Issues

The recover tool currently needs much memory - during recovery of my 4 GB partition with about 70,000 files, it needed about 100 MB RAM. This will be heavily reduced in later releases (at least optionally, as this will also slow down the operation a bit).


History

Version 0.7.6, May 25th, 2004

  • Added copy_to_bfs_image tool
  • internal improvements
Version 0.7.5, September 28th, 2003
  • added new tool bfswhich
  • the tools now accept more ways to identify a disk (like the mount point)
  • bfsinfo recognizes different representations to specify the block number
  • improved bfsinfo output
  • recover now can work on raw devices (where the partition table is corrupted)
  • improved documentation
Version 0.7.0, March 6th, 2002
  • initial release


Author & Address

The Address for bug-reports, ideas and other hopefully useful things:
Letter/Parcel post:
pinc Software / Axel Dörfler
Lange Straße 4a
49080 Osnabrück
Germany
eMail-Address:
axeld@pinc-software.de (Axel Dörfler)
WWW:
http://www.pinc-software.de
If you want to send small donations or cards - be welcome :)


Copyright & Disclaimer

The package is copyrighted ©2001-2004 by Axel Dörfler. All rights reserved.

You are allowed to copy it to other free- & shareware-pools as long as this documentation is included and you are not following any commercial interests.

The collection is currently distributed as giftware - if it rescued some precious data, or you are just so happy with it, you may consider to donate me some money, hardware, or cakes :-). Further releases may also be distributed commercially.

You may freely use this product as is. However, no warranty is given on any part of its functionality. In no event shall the author be liable for any damages it caused.


Copyright ©2001-2004 pinc Software. All Rights Reserved