BOCHS-TOOLS
===========

Bochs-Tools are a collection of scripts and programs to be used together
with the Bochs-emulator (see http://bochs.sourceforge.net). Main goal was
to provide a more Unix-like interface to the emulator and to enable
access to Bochs disk-images from outside of Bochs. With Bochs-Tools, it
is very simple to clone an existing OS-installation to a Bochs-image (as long
as Linux has write-access to the relevant file-system).

The tools were developed under Linux. They might also work on other
operating-systems. Feedback on this issue is appreciated.


SYNOPSIS
========

For a detailed usage-example, see below section EXAMPLE.

bxtactivate  : Activate a partition of a disk-image
bxtclone     : The all-in-one create, copy, lilo script
bxtcopy      : Copy a directory-tree to a disk-image partition
bxtcreate    : Create a partitioned disk-image. Only primary partitions
               are currently supported.
bxtdd        : Dump data to and from a partition of disk-image
bxtlilo      : Install lilo on the disk-image
bxtmkfs      : Create a filesystem on a disk-image partition. Supported
               filesystem-types: swap, minix, ext2, ext3, reiserfs, fat, fat32
bxtmount     : Mount a disk-image partition
bxtptinfo    : Outputs information about a disk-image
bxtsettype   : Set the partition-type of a partition of a disk-image
bxtsfdisk    : Run sfdisk on a disk-image
bxtstart     : Start the emulator. Floppy and disk-images are passed
               on the commandline using Unix-compliant options. The
               geometry and size of the floppy and disk-images is autodetected.
bxtfuncs.inc : (shared functions, internally used)

The bxt*-scripts also work with images created with bximage
and which were partitioned within the emulator. They
also support images created with dd as described in the "old"
Bochs-documentation.

The Bochs-Tools need sfdisk in the PATH, sfdisk is part of the 
util-linux-package and normally installed on every Linux-system.


INSTALLATION
============

The following steps are only necessary if you did not install
the rpm-package.

Unpack the Bochs-Tools archive (something like
bochs-tools-1.6.0.tar.bz2) and run "make install" as root.

# tar -xvjf bochs-tools-1.6.0.tar.bz2 -C /tmp
# cd /tmp/bochs-tools-1.6.0
# make install PREFIX=foo

PREFIX defaults to /usr/local. All executables will go into the
PREFIX/bin-directory, man-pages go to PREFIX/man/man1


DOCUMENTATION
=============

Man-pages are available. Every script/program supports the option "-h"
for runtime-help. And you have the sources!


EXAMPLE: Cloning an existing Linux-distribution
===============================================

Let's assume we have installed the Debian bootstrap installation of
Woody on /dev/sdb3 (about 110MB). We want to put this distribution on a
disk-image and start the emulator afterwards. The disk-image should
have two partitions, one for the distribution and a second for 
swap-space (128MB).

# bxtcreate -1 200m -2 128m hda.img   # create the image
# bxtmkfs -t ext2 hda.img:1           # make ext2-fs on first partition
# bxtmkfs -t swap hda.img:2           # make swap-space on second partition
# mount /dev/sdb3 /mnt                # mount Woody-installation
# bxtcopy /mnt hda.img:1              # copy Woody-tree to first partition
# umount /mnt                         # umount source
# bxtmount hda.img:1 /mnt             # mount first partition (the copy!)
# vi /mnt/etc/fstab                   # change mountpoint of / to /dev/hda1
                                      # and swap to /dev/hda2
# ln -fs hdc /mnt/dev/cdrom           # make sure that /dev/cdrom points to
                                      # /dev/hdc
# umount /mnt
# bxtlilo hda.img                     # install the lilo boot-loader
# bxtstart -b disk -1 hda.img         # start the emulator and boot from disk

The given procedure is much much faster than installing within the
emulator! It is probably not a good idea to use the disk-image
from within Bochs and from outside at the same time (although I haven't
tested that).

With the new bxtclone-script, things are even much simpler. If you don't
need fined-grained control, you can just use these commands:

# mount /dev/sdb3 /mnt                # mount Woody-installation
# bxtclone /mnt hda.img               # create, copy, lilo, ...
# umount /mnt
# bxtstart -b disk -1 hda.img         # start the emulator and boot from disk

bxtclone has a number of options to control partition-sizes, see the
man-page for details.


DOS/WINDOWS considerations
==========================

The above procedure can also be used to clone a DOS/Windows (exept NT and XP)
installation. If you create a pure DOS/Windows Bochs-image, you also need
to activate the first partition of your image and install the boot-code.

To do this, run "bxtactivate hda.img:1". Then boot the emulator with an 
appropriate rescue-disk and run "sys c:". Note that the rescue-disk created
from within Windows98 does not contain sys.com by default, you have to copy
it from c:\windows\command\sys.com.


Dual-boot DOS/Windows and Linux
===============================

The script bxtlilo will add a DOS/Windows partition to the boot-menu, if it
is on a partition before the Linux-partition (e.g. DOS: hda1, Linux: hda2,
swap: hda3). In this case, you only have to add the boot-code with "sys c:"
as described above, you do not have to activate the DOS/Windows partition.


Additional notes
================

If lilo complains "Sorry, don't know how to handle device 0x0701", you
should upgrade lilo to a more recent version. Note: the version of lilo
shipped with Red-Hat 8 is definitely too old!

---

"bxtcopy srcdir hda.img:1" is a shortcut for:

# bxtmount hda.img:1 /tmp/mnt
# tar -cpf - -C srcdir . | tar -xpf - -C /tmp/mnt
# umount /tmp/mnt

(In fact, bxtmount uses a temporary directory created with mktemp
instead of /tmp/mnt).

---

"bxtptinfo -b hda.img" outputs the geometry suitable for your bochsrc-file.

---

Due to a bug in Bochs up to 2.0.1, ata-definitions can't be changed from the
commandline. If you use bxtstart, you should comment out the definitions
for ata0-master, ata0-slave and ata1-master. These are set automatically
by bxtstart. There are two advantages of bxtstart compared against the
standard commandline interface of Bochs: geometry and size are autodetected,
and you can use filename-completion.


LICENSING ISSUES
================

Bochs-Tools are placed under the GPL version 2, see file COPYING.


SUPPORT
=======

If you think you found a bug or want to contribute some code please drop 
me a note. Include as much information as necessary (and possible). Be
aware that I only check my mail once or twice a week, so be patient.


Bernhard Bablok
mail@bablokb.de
http://www.bablokb.de

