How to install Rhapsody DR2 in VMWare
Introduction

Installing Rhapsody DR2 in VMWare is not quite as simple as OpenStep 4.2, as the monochrome VGA driver appears to be broken (intermittently), amongst other problems. Thus, we need to do some considerable quantity of commandline-wrangling before we get to that stage.

This document assumes that you're running VMWare under a UNIX of some description (probably Linux) - Windows users can make it up as they go along with analogous tools.

It also assumes that you have already imaged your Rhapsody DR2 install CD, install floppy, and driver floppy.

You will need mkisofs or some analogous tool on the host.

This procedure has been tested under VMWare 4.5.

Virtual Machine Setup

The VMWare guest machine I used had 128 MB RAM and a 4GB Virtual Disc and was set up for Linux/Other as far as OS goes (as this seems to make the VGA adaptor slightly less temperamental). The disc has to be IDE - while VMWare can emulate a BusLogic SCSI card, the Rhapsody BusLogic driver seems to Die Horribly on boot with it. I set up the network card to be bridged; you can make your own choices here.

This VM will run Rhapsody alone. This HOWTO will not tell you how to dual-boot it with anything else. You have been warned.

Initial Installation

Once you have the guest set up, you need to aim its floppy drive at the Install Disc image you created, and its CD-ROM drive at the Rhapsody CD Image you created. Then boot the Virtual Machine. When it reaches the boot prompt just press enter and let it start.

It will then ask you to choose your language. Being British I, under protest, chose the first option, for English/US Keyboard. It will ask you to confirm that you really want to do this (THIS IS NOT AN UPGRADE, etc). Choose 1 to confirm it. It will say "Loading Rhapsody" and then ask you to insert the Driver disc. Change the floppy drive to point to the driver disc image (menu item VM -> Removable Devices -> floppy0 -> Edit... may well be helpful here) and press return.

It will then ask you to choose a driver. Choose 7 repeatedly until you see "Primary/Secondary (Dual) EIDE/ATAPI Device Controller (v5.01)", then choose that one (it's 1 on my driver disc). It will ask you whether you need to install any more drivers; you do not need to, so choose 1. It should then bring up a framebuffer-style console.

This console will inform you that this is a development operating system and is likely to break horribly and asks if you're really sure you want to install it. We already know this, so choose 1 if you want to continue installing.

It will present you with the disc spec of the startup volume in your VM. Check that this is right and press 1 to install Rhapsody on this disc. It will then ask you whether you want to use the whole HD for Rhapsody or leave some space for DOS. Choose to use the whole disc for Rhapsody (option 1). It will ask you again whether you are sure you want to install Rhapsody. This is your last chance to bail out. Assuming you do want to, choose 1. The installation program will then format the disc and begin copying files.

After a while, it will tell you that it's finished doing that and that you need to remove the floppy disc and hit return. Disconnect floppy0. I tend also to, at this point, edit floppy0 so that it doesn't connect at startup time.

Press return and wait for the VM to reboot. Allow it to boot; if you're lucky, it'll get to the configuration screen. Reboot - do not save your configuration. If it gets 'stuck', wait for it to come up with "DPS Error: Invalid Context Port" and then reboot. When you get to the boot prompt booting from the hard disc, go into single user mode by using the -s option:

boot: -s

and press return. After the drivers and so forth load, you will be left at a root prompt. We're done here for the moment, so you can halt the VM:

# sync; sync; halt

And then power off the VM.

Building the Driver ISOs

There are three drivers you need to install; two need to be done at this stage (mouse and screen), and one can be done later (network). However, it's a good thing to put all three on an ISO now because it saves chopping and changing later. These drivers are designed for OpenStep, but seem to work with Rhapsody also.

Create a directory somewhere handy; I called mine 'vfb'. You need to download into this directory the following files:

Then in a terminal on the host (the VM at this point should still be powered off) cd into this directory. We need to get the drivers into a format that Rhapsody can certainly unpack easily from the command line; this is easy, as it has GNU tar - and a .compressed file is really a .tar.Z. It's also sensible to shorten the file names for ease of typing. So, once in the directory, run:

$ mv VMWareFB.config.compressed vmwarefb.tar.Z
$ uncompress vmwarefb.tar.Z
$ gunzip VMMouse-1.1.I.bs.tar.gz
$ mv VMMouse-1.1.I.bs.tar vmmouse.tar
$ gunzip VMXNet-1.1.I.bs.tar.gz
$ mv VMXNet-1.1.I.bs.tar vmxnet.tar

Then use mkisofs to create an ISO with all the tar files on:

$ cd ..
$ mkisofs -o rhdriv.iso vfb/*

CommandLine Wrangling

Aim the virtual CD drive at your new rhdriv.iso file and boot the VM up again. Make sure it boots from the hard disc, and when at the boot prompt, boot into single user mode using -s again:

boot: -s

Wait for the drivers to load and you will end up at a root prompt. We need the / partition to be writeable, so first fsck it and then mount it rw:

# fsck
# mount -w /

If fsck asks if you want to fix things, answer 'y'. If fsck complains about superblocks on sd0a, ignore it - that's the CD-ROM drive.

Once you've mounted / read-write, you need to create a mount point for the drivers and mount the CD:

# mkdir /vfb
# mount -t cd9660 /dev/sd0a /vfb

Then copy all the drivers off and unmount the cd:

# cp /vfb/*.tar /
# cd /
# umount /vfb
# rmdir /vfb

Now we need to untar the drivers and put them in the right place.

# gnutar xf vmwarefb.tar
# gnutar xf vmmouse.tar
# gnutar xf vmxnet.tar
# mv VMWareFB.config /private/Devices
# mv VMMouse/VMMouse.config /private/Devices
# mv VMXNet/VMXNet.config /private/Devices
# rm -rf VMMouse
# rm -rf VMXNet

The drivers are now ready to be set up. To set them to load at boot-time, you need to edit the /private/Devices/System.config/Default.table file. To do this, use vi:

# vi /private/Devices/System.config/Default.table

Note that as this terminal is not very featureful, the arrow keys don't work and nor do most of the other options. So you need to use the following navigation keys in vi:

 k
h l
j

You need to change the Active Drivers line to look like:

"Active Drivers" = "VMMouse ParallelPort VMWareFB";

To do this (for those not good at vi), press j until your cursor is at the beginning of the Active Drivers line, then press l until the cursor is over the first letter of PS2Mouse (which is what you're replacing). Press x repeatedly to delete the character under the cursor to get rid of all the mouse drivers in the list - leave the space before ParallelPort. Then press i and type VMMouse. '''Case is important, and it is entirely possible that caps lock will not work and you will have to hold down Shift to get capital letters'''. Then press escape to get back to command mode. Press $ to go to the end of the line and press h until you are over the first letter of VGA. Press x three times to erase the word VGA. then press i again and type VMWareFB. Then press escape. If you're satisfied that it's right, type :wq and press enter. This will save the file and quit vi. If you got it wrong, do a :q! and enter which will quit without saving, and then execute the vi command again.

To make this bit even more surreal, you may come across horribly disorientating redraw glitches in vi. If you hit them, save and exit vi and then re-execute the vi command and they should be gone. It's certainly a good idea to check that it's right at the end, by executing

# cat /private/Devices/System.config/Default.table

and making sure that the Active Drivers line is as shown above.

Configuring the Video Driver

The next trick is to configure the video driver. The reason for this is: '''the video driver's colour depth and colour model must match the host display's'''. Thus, 16 and 32 bit colour depths are good choices on the host - 24 bit might work (it does in my case). You need to find this from your X configuration - the chances are good that

$ cat /etc/X11/xorg.conf | grep DefaultDepth

will tell you (if you're running Xorg - if you're running XFree86 still - why? - it'll be cat /etc/X11/XF86Config-4 ... instead).

Once you've found this out, you need to edit /private/Devices/VMWareFB.config/Default.table with vi:

$ vi /private/Devices/VMWareFB.config/Default.table

and edit the Display Mode line by changing the depth on the end; as my screen depth is 24bpp, my line looks like

"Display Mode" = "Height: 768 Width: 1024 Refresh: 60Hz ColorSpace: RGB:888/24";

Note that this file is read only - to save it you will need to do a :w! then enter, then :q and enter to leave vi.

Once you have saved this file, cross all extremities, aim the virtual CD-ROM drive back at the Rhapsody Install ISO and reboot.

# reboot

Continuing Configuration

This time, just press enter at the boot prompt and let it load the GUI. If you have correctly set up the VMWareFB driver, you should see a configuration application (which will look like OpenStep, not Rhapsody - don't think you've installed the wrong OS when you see that chunky black title bar!) on a purple desktop in colour. If you see it in grey then you probably saved your configuration earlier when I told you not to - in which case you need to set up the VMWare driver now. If you see white noise, you got the colour depth wrong in the configuration of VMWareFB.

You now need to install the network driver. To do this, click on the Globe icon at the top of the configuration window. It should search for drivers and show the VMXNet driver as the only one. Click on this and choose add.

Information on Sound Driver hopefully forthcoming!

When you've done this, click on Done, then Save at the bottom of the configuration window.

It will then prompt you what you want to install. For some reason on my copy it would not install unless I unchecked everything except 'Rhapsody Essentials'. If it doesn't like what you've selected it'll just throw you back to the install menu. If it does like it, it'll install what you chose and then say that it has completed.

Click Restart and your Virtual Machine will boot into Rhapsody for the first time.

That's the theory anyway.

The Setup Assistant

Once the system has rebooted you will be presented with the Setup Assistant. Click on the little Next arrow in the bottom right hand corner of the window to start changing your settings.

First, you will be asked to choose your keyboard layout. If in doubt, select the one that looks plausible and then click on "Show Layout"; as you type on the keyboard the appropriate keys on the layout will light up so you can check that the keys line up correctly. Holding down the modifier keys will show the effect this has on the keyboard. Once you're done playing with the 'Show Layout' dialog, press 'OK'.

Once you've got the correct keyboard layout chosen, click on the little Next arrow again.

Next, you will need to set up the network. It will offer you the choice of automatic assignment (DHCP, presumably) or manual - for my setup I need manual, so I selected that and clicked Next and filled in my IP address, subnet mask, and router. You will then be asked if you want to use NetInfo - if you don't know that you do, you don't. Choose No and press next and it will ask you to input your DNS servers.

You will then be asked for your geographical location. Click on the map roughly where you are and then choose a more precise location in the drop-down box. If you are in Britain do not choose GMT, choose Britain, or it will get all confused about BST.

You will then be asked whether you want to synch up with NTP servers - I recommend you do this if you have a time server roughly handy. If not, then you can set the time manually.

There should then be an explanatory pane about user accounts; click next and you will be given the option of creating a new local user account. You need to do this, so choose Yes. You will then be prompted for a username and full name for this account. Fill these in and click next, whereupon it will prompt you for a password for this account. Enter it twice and click Next. You will then be prompted whether you want automatic login. Choose and click Next. Then it will ask you to set a root password. Set a good root password.

It should then say that it is ready to make the changes. Click 'Go Ahead' - when the changes have been made it will ask you to reboot. Click on the 'Restart' button and wait for the system to come back up.

Congratulations. You should now have a working Rhapsody installation.