HOWTO use VirtualBox to run simulations on Windows machines
ns-3 is primarily a Linux platform, and advanced ns-3 features will use Linux specific functions to accomplish their goals. Since Windows is such a widely used platform, ns-3 does provide a supported solution for running in that environment using a Linux-emulation environment called Cygwin. However, Cygwin is not a perfect emulation of any Linux. This means there will be features available on Linux systems that are simply not usable on Windows systems.
Fortunately, a technology called virtualization exists to allow one to share computer hardware between operating systems and allow you use Linux systems essentially as if they were running natively on your hardware. This happens as your Windows is running, so it appears as if Windows and Linux are sharing your hardware.
There are several virtualization schemes currently available. Two of the most popular are VMware (see HOWTO use VMware to set up virtual networks (Windows)) and VirtualBox. We will cover VirtualBox in this HOWTO. The following image is a screenshot of Fedora running as a virtual machine on a Windows XP (classic) desktop. You can probably make out that the terminal session on Fedora has just completed running the ns-3 test suite (test.py).
HOWTO use VirtualBox to run simulations on Windows machines
1. The first thing you must do is get the VirtualBox binaries.
a. Go to the VirtualBox downloads page b. Download and run the VirtualBox binary for Windows Hosts by clicking on the x86/amd64 link. You will get the usual File Download - Security Warning dialog. Just click Run to download and run the about 70 megabyte file. c. After the file downloads, you will get the usual Windows Internet Explorer - Security Warning dialog. Just select Run.
2. Step through the Sun VirtualBox Setup Wizard.
a. Press the Next > button. b. Accept the terms of the license agrreement (if you desire) by clicking the corresponding radio button. c. Press the Next > button. d. Review the features that will be installed if you desire. I just accept them as-is. e. Press the Next > button. f. Decide if you want a desktop and quick lanch icon. If you expect to use ns-3 a lot it is probably worthwhile, but completely up to your preference. g. Press the Next > button.
3. Perform the actual installation. Warning: This step will temporarily disconnect you from the Internet.
a. Press the Install button to start the installation process. b. You will see a number of dialog boxes (six) complaining that VirtualBox has not passed Windows Logo Testing. Press Continue Anyway. c. When you see the Sun VirtualBox installation is complete message leave the Start Sun VirtualBox after installation radio button selected. d. Press the Finish button.
4. Register with Sun Online. VirtualBox will ask you to register with Sun Online. If you already have a Sun Online account, enter it or just fill out the account creation part of the page and press Register. If the registration process complains about a bad IP address, just create a new account.
Sidebar: In this HOWTO, we explain how to download a CD image from the web and use it to install a guest operating system in VirtualBox. There is an alternative, which is to start with a pre-configured OS "Virtual Applicance." These are VMware things, but VirtualBox can read them. You can browse through hundreds of applicances here.
5. Download a Linux CD image.
a. Decide which version of Linux you are going to use. If you have no strong preference, I would use the same version that ns-3 does most of its testing on. Look here for the ns-3 wiki. Follow the Buildbot Waterfall Display link, and notice the list of platforms. At the time of this writing, most of them are fc10. This translates to Fedora Core 10. You can infer that ns-3 testing is mostly performed on Fedora systems, so Fedora it is; and Fedora 12 is the latest release as of this writing. b. Go to The Fedora Project and then to Get Fedora and download a CD image. You will get the usual File Download - Do you want to open or save this file? dialog. Just click Save and tell the system where to put the almost 700 megabyte file.
6. Create a new virtual machine.
a. Go to the Sun VirtualBox window you started in step 3. b. Press the "New" button. This will start a New Virtual Machine Wizard. c. Press Next > in the wizard. d. Give your new virtual machine a name, say "ns-3-fedora-12". e. In the OS Type box, select Linux as the Operating System and Fedora as the Version. f. Press Next > in the wizard. g. Keeping in mind how much physical memory you have in your host machine, give the new virtual machine some memory. This won't be available for your host machine. I choose 512 MB on my 2 GB Windows machine. h. Press Next > in the wizard. i. Keeping in mind how much hard disk space you have in your host machine give the new virtual machine some memory. You will need disk for the base OS, the toolchain and at least one ns-3 distribution, which will require about 1.2 gig at the time of this writing. j. Press Next > in the New Virtual Machine Wizard to start the Create New Virtual Disk Wizard. k. Press Next > in the Create New Virtual Disk Wizard. l. Leave the Dynamically expanding storage radio button selected and press Next > in the Create New Virtual Disk Wizard. m. Select a maximum size for the disk (I use 10 GB) and press Next > in the Create New Virtual Disk Wizard. o. Press Finish in the Create New Virtual Disk Wizard to create your disk. p. This takes you back to the New Virtual Machine Wizard which will be giving you a summary of the new virtual machine parameters. Press Finish in the Create New Virtual Disk Wizard to create your new virtual machine.
7. "Insert" your boot CD. In the Sun VirtualBox window, you should now see avirtual machine named "ns-3-fedora-12" in the powered off state on the left side. On the right side, you should see the "Details" tab selected, with the details for "ns-3-fedora-12" displayed.
a. Click on the Storage item. b. Under Storage Tree box, IDE Controller, select the secondary master which should say Empty at this point. c. Under the Attributes item there is a pulldown labeled CD/DVD Device. Select the folder icon to the right. This will load the VirtualBox Virtual Media Manager. d. Select the Add action and navigate to the folder in which you saved the Fedora 12 iso image above. Select the iso image which will insert it as if it were a real CD. e. Press OK to return to the main VirtualBox window.
8. Power up the virtual machine and install Fedora 12.
a. Select the Start icon in the Sun VirtualBox window. It is shaped like a green arrow. b. Read the information dialog about how to get in and out of the virtual machine window and press OK. c. Read the information dialog about color mode and press OK. d. Click into the new virtual machine window, select Capture and watch Fedora 12 start to install (this will take a while). e. When the login box appears, press "Log In" and then double click the Install to Hard Disk icon. f. Press Next to begin the Fedora 12 installation process and copy the image to the virtual machine hard drive. This is going to take some considerable time since you are installing a whole operating system. We won't cover how to proceed here in detail since this is not a Fedora 12 installation guide. Do remember that you will have to initialize your virtual hard disk since you just "created" it. Google is your friend if you have problems. g. Eventually you'll see "Congratulations, your Fedora installation is complete". Press Close. h. Shut down the Fedora system.
9. "Remove" your boot CD. In the Sun VirtualBox window, you should now see a virtual machine named "ns-3-fedora-12" in the powered off state on the left side. On the right side, you should see the "Details" tab selected, with the details for "ns-3-fedora-12" displayed.
a. Click on the Storage item. b. Click on the Fedora-12-i686-Live.iso CD in the IDE Controller under Storage Tree. c. Select Empty under the CD/DVD Device pulldown. d. Press OK.
10. Bring up your shiny new Fedora 12 system.
a. Select the Start icon in the Sun VirtualBox window. It is shaped like a green arrow. b. You'll have to do a few more setup steps (create a user) in the Fedora Setup Agent. This will reboot one more time and then you can log in with your new user name.
11. Install the GNU toolchain and some useful tools. If you have added yourself as a sudoer, you can run the following commands (or others according to your taste) using sudo, otherwise log on as root. A more complete list is available here.
a. yum install libxml2 libxml2-devel b. yum install gcc gcc-c++ make automake autoconf binutils c. yum install openssh-server openssh-clients openssl d. yum install python python-devel mercurial bzr e. yum install scons flex bison f. yum install tcpdump valgrind gdb emacs
12. Get and Test ns-3-dev
a. Make sure you have exited from su root, if you did that in step 11. b. cd ~ c. mkdir repos d. cd repos e. hg clone http://code.nsnam.org/ns-3-allinone f. cd ns-3-allinone g. ./download.py h. ./build.py i. cd ns-3-dev j. ./test.py k. ./waf --regression
As an old math professor once said, "I feel joy"!
If you are really going to use a virtual machine as a primary development platform, you will probably be annoyed by the limitation of the device driver to 800x600 resolution. You can fix this by installing the so-called VirtualBox Guest Additions. This will aso get rid of the annoying "mouse capture" and "mouse release" business. If you install the Guest Additions, you can resize your virtual desktop to any size you want and mouse in and out of it just as if you were in a Windows window. Recommended. The screen shot at the top of the page was taken of a my home system which has these additions enabled. See the VirtualBox documentation for instructions, perhaps starting here in the user manual.
Craigdo 22:21, 7 November 2009 (UTC)