[vbox-dev] My first patch for official Innotek dcoumentation

Alexey Eremenko al4321 at gmail.com
Fri Mar 16 21:06:01 GMT 2007 

Hi all !

Since Docbook XML sources not available, I did my series of patches in
plain-text format according to Michael Thayer's recommendations.

Those patches are meant to be added to Official Innotek dcoumentation
and be included in the product itself.

Please review it, and make comments.

NOTE: USB section written by Pablo Schraitle, but he agreed to publish
this. (with little updates from me). All other material is written by
me.

I have agreed to work with InnoTek with one requirement: the
documentation must be available with the product itself, so Michael
recommended me to patch the original one.
Since sources are not available I had to develop my own scheme of
patching, and I hope you understand me.

So, what do you think of it?

-- 
-Alexey Eremenko "Technologov"
-------------- next part --------------
 VirtualBox Documentation Improvement
======================================
File made by Alexey on 16.03.2007.
Draft.

What to improve:
-Guest OSes supported list
-Adobe reader needed on Windows host
DONE
-Host-Network: where to get uml-utils? (link to URL)
DONE
-SUSE-host specific issues (USB, ...) - 10.4.6 must be rewritten.
DONE
-Update hardware requerements ?
DONE
-step-by-step Host-Networking setup on Windows XP Host
-add some GUI-configuration stuff, not just VBoxManage
-Porting VMs to be added. (between sections 5 and 6)
DONE

Legend:
+> added line.
-> removed line.
m> modified line.

===============================================
Chapter 2. Installation

As installation of VirtualBox varies depending on your host operating system, we provide installation
instructions in two separate chapters for Windows and Linux, respectively.
+>
+>Minimum Hardware Requirements:
+>
+>Intel Pentium II CPU (Intel Core 2 recommended)
+>512 MB of RAM (several gigs of RAM recommended)
+>10 GB Hard Disk
+>

2.1. Installing on Windows hosts
===============================================
Section 2.1.1
...
In addition, Windows Installer 1.1 or higher must be present on your system. This should be the
case if you have all recent Windows updates installed.
+>
+> Adobe Reader must also be installed to read our PDF documentation.
+>
Note

Presently VirtualBox can only be run from user accounts with administrator rights. This
will be fixed in a future release.
...
===============================================

Section 5.3.3.2. Bridging on Linux hosts

...
For information how to create TAP devices, please refer to the documentation of your distribution.
Often, this can be accomplished using the tunctl utility, which is part of the User Mode Linux
project. For example, on Gentoo Linux, this can be found in the sys-apps/usermode-utilities
m> package. For other Linux distros, you must get the sources from 
+> http://prdownloads.sourceforge.net/user-mode-linux/uml_utilities_20040406.tar.bz2
+> and compile manually.
+>
+> Other useful links, that discuss UML utilities and tunctl: 
+> http://user-mode-linux.sourceforge.net/dl-sf.html and 
+> http://user-mode-linux.sourceforge.net/networking.html#daemons

Bridging, then, is a feature provided by the Linux kernel and can be controlled with the brctl command from another utility package. For example, on Gentoo, this can be found in the netmisc/
bridge-utils package.
===============================================
A totally new chapter !!! (actually I strongly recommend to put it between ch.5 and ch.6.)

Chapter 6: Backup, Restore and Porting of VMs Between Physical Machines

Your VMs configuration can be found at ~/.VirtualBox/ on Linux Host, and 

Your VMs are combined of 3 things: The software - VirtualBox - no major need to backup this usually, as this can be downloaded from the Internet. 

Your virtual hard disk - this is the most important thing to backup, 
and your VM configuration - which virtual hardware is used. Also, since the versions of VirtualBox are a bit different between Windows and Linux, that configuration files will work across different Host platforms. 
This is especially true due to the fact that different machines might have different Host-Network TAP configurations.

It's recommended for you to save virtual Hard Disks only. There is no need to save VM configurations. Managing saved VMs with a simple rule: 1 file = 1 VM is easier.

   1.      Before you back-up them, you can customize according to your needs, install basic utilities, patches, and optionally install Guest VM Additions.

   2.     Make sure you shutdown the VM normally, throught Guest OS commands (Start->shutdown, or init 0 on Linux Guests), without pull-virtual-power-plug (do not just close VirtualBox, as this can damage your filesystem on virtual hard disk) and make sure you have no saved states.

   3.      Search for *.vdi to find all Virtual Hard Disks. Now save all your *.vdi files somewhere, perhaps on DVDs. Optionally compress them first with zip, so the archives will be cross-platform.

   4.      When you restore your *.vdi files on some other machine, the Host OS can be different. Windows or Linux, doesn't matter.

   5.      Create new VMs, and use existing Virtual Hard Disks, from the just restored DVDs. 

Interoperability Tip: This method can work for Dual-Boot systems very well. You must have all your .vdi files on NTFS partition, and access it with NTFS-3G driver. Before you restart to a different Host OS, please shutdown GuestOS properly, as described earlier. FAT32 partitions won't work, because they are limited to 4GiB per .vdi file. 

* Troobleshooting + Tips

When backuping your VMs, small problems may arise:

a) You might have a problem of changed MAC address, so some guest OSes will install a new NIC driver for you.

b) Make sure you don't install software that requires specific CPU instructions, such as SSE. (because this will render the VM as non-portable, as not all CPUs support SSE). Fortunately, 99.9% of software don't have this issue.

c) saved state will be lost, so you have to shutdown the VM properly. 
===============================================
This is done by Pablo Sanchez from http://www.blueoakdb.com

10.4.6. USB not working

m> If USB is not working on your Linux host, make sure that your kernel supports usbfs 
+> (openSUSE 10.2 doesn't) and
that the current user has permission to access
the USB filesystem (usbfs), which VirtualBox relies on to retrieve valid information about your
host's USB devices.

As usbfs is a virtual filesystem, a chmod on /proc/bus/usb has no effect. The permissions for
usbfs can therefore only be changed by editing the /etc/fstab file.
...
Other distributions do similar operations in scripts stored in the /etc/init.d directory.
+>
+>On SUSE systems, due to lack of usbfs kernel-module, you will have to build a new kernel.
+>
+>1. Install the following kernel packages:
+>
+>- kernel-source
+>- kernel-syms
+>
+>2. Recompile and install the openSUSE 10.2 stock kernel with:
+>
+>CONFIG_USB_DEVICEFS=y 
+>
+>3. Reinstall VirtualBox
+>
+> Slower bootup of VM:
+>
+>I've noticed the VM (W2K) takes longer to boot up after this addition. On my Dell Insprion 8200 with +>a +>P4/1.6GHz chip, about an extra eight seconds. I didn't collect hard numbers and it doesn't concern me 
+>as it's only during boot up of the VM. 
+>
===============================================


Legend:
+> added line.
-> removed line.
m> modified line.

More information about the vbox-dev mailing list