3 NeuroDebian Virtual Machine
4 ===========================
10 For those who are not yet running a Debian-based operation system we offer a
11 `virtual machine`_ that can be used with `VirtualBox`_, allowing users to benefit
12 from a Debian-based research environment on other operating systems.
13 This virtual machine initially comes as a compact Debian installation that can,
14 once installed, be equipped with a large variety of neuroscience software with
15 just a few mouse clicks (e.g. AFNI_, Caret_, FSL_, PyMVPA_).
17 .. _virtual machine: http://en.wikipedia.org/wiki/Virtual_machine
18 .. _AFNI: http://afni.nimh.nih.gov/afni/
19 .. _Caret: http://brainvis.wustl.edu/wiki/index.php/Caret:About
20 .. _FSL: http://www.fmrib.ox.ac.uk/fsl/
21 .. _PyMVPA: http://www.pymvpa.org
27 The virtual machine contains an installation of `Debian 6.0 (squeeze)`_ with a
28 GNOME_ desktop environment. All installed software comes from standard Debian
29 packages, or prospective Debian packages from NeuroDebian. This means that all
30 contained software is readily available for any system running a Debian
31 operating system (or a recent Ubuntu release). The virtual machine can be seen
32 as a showcase of what Debian for neuroscience research feels like. Moreover,
33 once downloaded this virtual machine can be kept up to date, just as any other
34 Debian installation. Using convenient graphical package management tools users
35 will benefit from security bug fixes provided by the Debian project for the
36 whole operating system, as well as from software updates for
37 neuroscience-related packages.
39 .. _Debian 6.0 (squeeze): http://www.debian.org/releases/squeeze
40 .. _GNOME: http://www.gnome.org/
46 The following video shows how to get the NeuroDebian virtual machine running
47 on your machine. The installation is shown for Mac OS X. It should, however, be
48 very similar on a Windows box. If you cannot watch the video, please take a
49 look at the written instructions below.
53 <iframe title="YouTube video player"
54 class="youtube-player"
58 src="http://www.youtube.com/embed/eqfjKV5XaTE?hd=1"
59 frameborder="0"></iframe>
61 First download and install a recent version of VirtualBox_. VirtualBox is a
62 virtualization software that is freely available for Windows, MacOS X, Solaris,
63 and Linux. VirtualBox comes with a comprehensive manual that should answer
64 potential questions regarding installation and maintenance.
66 .. _VirtualBox: http://www.virtualbox.org
68 Next, download the most recent version of the NeuroDebian virtual machine from
69 the Downloads_ section. Start VirtualBox and select "Import Appliance" from the file
72 .. image:: pics/vm_import_app.jpg
74 The next dialog will ask you to choose a virtual machine. Please navigate to the
75 extracted NeuroDebian download and select the `.ova` (or extracted
76 `.ovf` for older appliances shipped as `.zip`) file.
78 .. image:: pics/vm_import_wizard.jpg
80 You can finish importing of NeuroDebian by clicking on *next* a couple of
81 times. There is no need to change anything, as we will get through the
82 settings in a second. Importing of the virtual machine will take a short
83 while, as it is distributed in a compressed format that now gets extracted
84 (total extracted size about 2 GB). Once imported, the NeuroDebian virtual
85 machine will appear in the list of available machines. Do **not** start it yet,
86 but select NeuroDebian and hit the *Settings* button. In the following dialog
87 you'll have a chance to configure the machine. You can assign the amount of RAM
88 that should be made available to it (for serious fMRI data processing, please
89 allow at least 2 GB). If you have a recent computer with multiple CPU cores,
90 you can also decide how many cores should be used by the virtual machine.
92 .. image:: pics/vm_add_host_folder.jpg
94 However, most important is the *Shared Folders* setup. Shared folders allow the
95 virtual machine to access the local harddrive of the host computer. This is an
96 easy way to access data on the computer without duplicating it or using the
97 network to access it. The virtual machine is preconfigured to access a shared
98 folder named labeled "host". Click on the *add* button to select a folder that
99 shall be accessible by the machine (e.g. your home directory) and put "host" as
100 the folder name and mark it to be auto-mounted. Note, the folder name is simply a label. Your directory will
103 .. image:: pics/vm_host_folder.jpg
105 If you have a large screen you should increase the display memory to
106 32 MB in the *Display* settings. Also you might like to enable the
107 support for 3D Acceleration
109 .. image:: pics/vm_settings_display.jpg
111 Finally, close the settings dialog. You have now completed the setup, and you
112 can start the virtual machine by hitting the *Start* button. A new window will
113 appear showing the boot process. After a short while the NeuroDebian desktop
114 will appear, and a setup wizard will guide your through the final steps of the
115 configuration. You can now explore the system. The virtual machine is connected
116 with your host computer, and shares its Internet connection. Via this
117 connection you can update the contained software packages at any time.
119 .. image:: pics/vm_settings.jpg
121 The virtual machine logs yourself in automatically. The name of the virtual
122 machine user is `brain` and the password is `neurodebian`. The *root* password
123 is also `neurodebian`. In most cases, however, you should not be forced to type
124 the password, since `sudo` is configured to work without it.
128 For increased security you might want to change the default password. You can
129 do so by opening a terminal window and running the ``passwd`` command.
132 Working with the virtual machine
133 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
135 The next video is a demonstration of some basic desktop integration features.
136 It shows how to use the virtual machine in full-screen and seamless mode, shared
137 folder access, software installation, as well as suspending and resuming the
142 <iframe title="YouTube video player"
143 class="youtube-player"
147 src="http://www.youtube.com/embed/OV7fYSEoOeQ?hd=1"
148 frameborder="0"></iframe>
151 .. _chap_vm_troubleshooting:
158 <div class="expandinstructions">Click on an item to expand it</div>
160 Updating the VM or installing new packages doesn't work
161 The VM uses as service that tries to figure out the best/closest package
162 repository for you. In some network environments this service might not work
163 well, or not at all. To check if this is a problem, you can modify the
164 respective configuration by hand. Edit ``/etc/apt/sources.list`` (you need to
165 use ``sudo`` for that) and replace the package repository URL with a mirror
166 close to you. A comprehensive list of mirrors is available at:
167 http://www.debian.org/mirror/list
169 Pick one and replace all ``geomirror.debian.net`` URLs with the new mirror
170 URL. For example, in Canada you might want to change::
172 deb http://i386-geomirror.debian.net/debian squeeze main non-free contrib
176 deb http://ftp.ca.debian.org/debian/ squeeze main non-free contrib
178 Only modify lines that refer to ``geomirror`` (all of them), but do **not**
179 modify entries for ``security.debian.org``.
181 I cannot hear sounds played in the virtual machine
182 By default the sound is muted. To enable playback launch the mixer applet by
183 clicking on the mixer icon in the task bar. Unmute the master volume control.
184 Now click on the "Volume control" to load the channel mixer dialog. Unmute
185 the "Master" and "PCM" channels and raise the volume as desired. You should
186 now be able to hear sounds played within the virtual machines through your
187 host computer's speakers.
189 My VM lost mounted host directories after upgrading from VirtualBox from 3.x to 4.x
190 NeuroDebian VMs prior 6.0.3 were shipped with guest additions from
191 3.x series of VirtualBox and some initial versions of VirtualBox in
192 4.x series have failed to mount host directories properly.
193 VirtualBox 4.0.8 seems to work fine with guest additions from 3.x
194 series. If you nevertheless want to upgrade guest additions within
195 NeuroDebian VM, please rebuild the version available from the
198 sudo apt-get install -y linux-headers-2.6-amd64 # or -686 for 32bit
199 sudo apt-get install -y -t squeeze-backports virtualbox-ose-guest-dkms \
200 virtualbox-ose-guest-utils virtualbox-ose-guest-x11
210 <div class="expandinstructions">Click on an item to expand it</div>
213 * Updated core system to Debian squeeze 6.0.3
214 * Updated shipped virtualbox-ose guest-utils and guest-x11 to 4.0.10
216 - ``~/host`` is now symlinked to correct path ``/media/sf_host``
217 - ``brain`` user is added to ``vboxsf`` group so mounted host
218 directories should become readily available
220 * Root partition size and swap space got doubled in size (40GB
221 and 2GB correspondingly). Space is allocated dynamically so
222 the actual size of the virtual drive should not grow unless
226 * Updated shipped virtualbox-ose guest-utils and guest-x11 to 4.0.4
228 6.0.3 -- 12 Jun 2011 [Superseded in the archive by 6.0.4]
229 * Updated to Squeeze 6.0.1
230 * Updated VirtualBox guest additions to 4.0.4 from backports.debian.org
231 * Appliance is available as a single file (.ova) ready for the import