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
26 Based on current stable `Debian 6.0 (squeeze)`_ release. This VM
27 provides a stable, well tested environment with the most of the recent
28 releases available from NeuroDebian.
30 * `NeuroDebian 6.0.6 image (32bit)
31 <http://neuro.debian.net/debian/vm/NeuroDebian_6.0.6_i386.ova>`_ [~559MB]
33 *This image should work on virtually all systems that are supported by*
34 VirtualBox_ *and can be used whenever the, otherwise preferable, 64bit image
35 is not compatible with a host machine.*
37 * `NeuroDebian 6.0.6 image (64bit)
38 <http://neuro.debian.net/debian/vm/NeuroDebian_6.0.6_amd64.ova>`_ [~576MB]
40 *This image only works on 64bit host machines with active hardware
41 virtualization support. The should include all recent Apple hardware and most
42 64bit Windows systems.*
44 Development (to be 7.x series)
45 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
47 Based on upcoming `Debian 7.0 (wheezy)`_ release. Although already
48 quite stable, there might be outstanding issues. This VM also
49 switches from GNOME_ (v.2) desktop environment to XFCE4_. We
50 recommend this VM over a stable one for anyone needing recent releases
51 of tools not available for the stable VM (e.g. recent pandas) --
52 **getting a complete "Scientific Python" stack with 100s of other
53 Python modules was never easier**. Moreover your feedback might also
54 be valuable to polish upcoming Debian wheezy release and NeuroDebian
57 * `NeuroDebian 6.999.b4.20130421 image (32bit)
58 <http://neuro.debian.net/debian/vm/NeuroDebian_6.999.b4.20130421_i386.ova>`_ [~670MB]
60 * `NeuroDebian 6.999.b4.20130421 image (64bit)
61 <http://neuro.debian.net/debian/vm/NeuroDebian_6.999.b4.20130421_amd64.ova>`_ [~670MB]
67 Virtual appliances above carry guest additions for 4.x series of the
68 VirtualBox. If you still have VirtualBox 3.x, use previous 6.0.2
71 * `NeuroDebian 6.0.2 image (32bit)
72 <http://neuro.debian.net/debian/vm/neurodebian_6.0.2_i386.zip>`_ [~545MB]
74 * `NeuroDebian 6.0.2 image (64bit)
75 <http://neuro.debian.net/debian/vm/neurodebian_6.0.2_amd64.zip>`_ [~560MB]
79 This older virtual appliances are distributed as a `zip` file. Please
80 extract all files from the `.zip` file, using appropriate software
81 for your operating system.
85 You can verify that you have downloaded archives correctly using
87 <http://neuro.debian.net/debian/vm/MD5SUMS>`_ . You can also verify
88 the authenticity of the `MD5SUMS
89 <http://neuro.debian.net/debian/vm/MD5SUMS>`_ itself using `gpg
91 <http://neuro.debian.net/debian/vm/MD5SUMS.gpg>`_ signed with
92 NeuroDebian archive key.
94 * `VirtualBox download page <http://www.virtualbox.org/wiki/Downloads>`_ (Windows, Linux, Mac,
97 *This webpage offers installers of the VirtualBox application, as well as the
103 6.999.b4.20130421 -- 22 Apr 2013
105 * Refreshed VM appliance to avoid lengthy initial upgrade
107 6.999.b4.20121231 -- 31 Dec 2012
109 * Based on beta 4 release of debian-installer_ for wheezy
110 * Comes with XFCE4_ instead of GNOME_
114 * Updated core system to Debian squeeze 6.0.6
118 * Updated core system to Debian squeeze 6.0.3
119 * Updated shipped virtualbox-ose guest-utils and guest-x11 to 4.0.10
121 - ``~/host`` is now symlinked to correct path ``/media/sf_host``
122 - ``brain`` user is added to ``vboxsf`` group so mounted host
123 directories should become readily available
125 * Root partition size and swap space got doubled in size (40GB
126 and 2GB correspondingly). Space is allocated dynamically so
127 the actual size of the virtual drive should not grow unless
132 * Updated shipped virtualbox-ose guest-utils and guest-x11 to 4.0.4
134 6.0.3 -- 12 Jun 2011 [Superseded in the archive by 6.0.4]
136 * Updated to Debian squeeze 6.0.1
137 * Updated VirtualBox guest additions to 4.0.4 from backports.debian.org
138 * Appliance is available as a single file (.ova) ready for the import
147 The virtual machine contains an installation of `Debian 6.0 (squeeze)`_ with a
148 GNOME_ desktop environment. All installed software comes from standard Debian
149 packages, or prospective Debian packages from NeuroDebian. This means that all
150 contained software is readily available for any system running a Debian
151 operating system (or a recent Ubuntu release). The virtual machine can be seen
152 as a showcase of what Debian for neuroscience research feels like. Moreover,
153 once downloaded this virtual machine can be kept up to date, just as any other
154 Debian installation. Using convenient graphical package management tools users
155 will benefit from security bug fixes provided by the Debian project for the
156 whole operating system, as well as from software updates for
157 neuroscience-related packages.
164 The following video shows how to get the NeuroDebian virtual machine running
165 on your machine. The installation is shown for Mac OS X. It should, however, be
166 very similar on a Windows box. If you cannot watch the video, please take a
167 look at the written instructions below.
171 <iframe title="YouTube video player"
172 class="youtube-player"
176 src="http://www.youtube.com/embed/eqfjKV5XaTE?hd=1"
177 frameborder="0"></iframe>
179 First download and install a recent version of VirtualBox_. VirtualBox is a
180 virtualization software that is freely available for Windows, MacOS X, Solaris,
181 and Linux. VirtualBox comes with a comprehensive manual that should answer
182 potential questions regarding installation and maintenance.
184 .. _VirtualBox: http://www.virtualbox.org
186 Next, download the most recent version of the NeuroDebian virtual machine from
187 the Downloads_ section. Start VirtualBox and select "Import Appliance" from the file
190 .. image:: pics/vm_import_app.jpg
192 The next dialog will ask you to choose a virtual machine. Please navigate to the
193 extracted NeuroDebian download and select the `.ova` (or extracted
194 `.ovf` for older appliances shipped as `.zip`) file.
196 .. image:: pics/vm_import_wizard.jpg
198 You can finish importing of NeuroDebian by clicking on *next* a couple of
199 times. There is no need to change anything, as we will get through the
200 settings in a second. Importing of the virtual machine will take a short
201 while, as it is distributed in a compressed format that now gets extracted
202 (total extracted size about 2 GB). Once imported, the NeuroDebian virtual
203 machine will appear in the list of available machines. Do **not** start it yet,
204 but select NeuroDebian and hit the *Settings* button. In the following dialog
205 you'll have a chance to configure the machine. You can assign the amount of RAM
206 that should be made available to it (for serious fMRI data processing, please
207 allow at least 2 GB). If you have a recent computer with multiple CPU cores,
208 you can also decide how many cores should be used by the virtual machine.
210 .. image:: pics/vm_add_host_folder.jpg
212 However, most important is the *Shared Folders* setup. Shared folders allow the
213 virtual machine to access the local harddrive of the host computer. This is an
214 easy way to access data on the computer without duplicating it or using the
215 network to access it. The virtual machine is preconfigured to access a shared
216 folder named labeled "host". Click on the *add* button to select a folder that
217 shall be accessible by the machine (e.g. your home directory) and put "host" as
218 the folder name and mark it to be auto-mounted. Note, the folder name is simply a label. Your directory will
221 .. image:: pics/vm_host_folder.jpg
223 If you have a large screen you should increase the display memory to
224 32 MB in the *Display* settings. Also you might like to enable the
225 support for 3D Acceleration
227 .. image:: pics/vm_settings_display.jpg
229 Finally, close the settings dialog. You have now completed the setup, and you
230 can start the virtual machine by hitting the *Start* button. A new window will
231 appear showing the boot process. After a short while the NeuroDebian desktop
232 will appear, and a setup wizard will guide your through the final steps of the
233 configuration. You can now explore the system. The virtual machine is connected
234 with your host computer, and shares its Internet connection. Via this
235 connection you can update the contained software packages at any time.
237 .. image:: pics/vm_settings.jpg
239 The virtual machine logs yourself in automatically. The name of the virtual
240 machine user is `brain` and the password is `neurodebian`. The *root* password
241 is also `neurodebian`. In most cases, however, you should not be forced to type
242 the password, since `sudo` is configured to work without it.
246 For increased security you might want to change the default password. You can
247 do so by opening a terminal window and running the ``passwd`` command.
250 Working with the virtual machine
251 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
253 The next video is a demonstration of some basic desktop integration features.
254 It shows how to use the virtual machine in full-screen and seamless mode, shared
255 folder access, software installation, as well as suspending and resuming the
260 <iframe title="YouTube video player"
261 class="youtube-player"
265 src="http://www.youtube.com/embed/OV7fYSEoOeQ?hd=1"
266 frameborder="0"></iframe>
269 .. _chap_vm_troubleshooting:
274 Updating the VM or installing new packages doesn't work.
276 The VM uses as service that tries to figure out the best/closest package
277 repository for you. In some network environments this service might not work
278 well, or not at all. To check if this is a problem, you can modify the
279 respective configuration by hand. Edit ``/etc/apt/sources.list`` (you need to
280 use ``sudo`` for that) and replace the package repository URL with a mirror
281 close to you. A comprehensive list of mirrors is available at:
282 http://www.debian.org/mirror/list
284 Pick one and replace all ``geomirror.debian.net`` URLs with the new mirror
285 URL. For example, in Canada you might want to change::
287 deb http://i386-geomirror.debian.net/debian squeeze main non-free contrib
291 deb http://ftp.ca.debian.org/debian/ squeeze main non-free contrib
293 Only modify lines that refer to ``geomirror`` (all of them), but do **not**
294 modify entries for ``security.debian.org``.
296 I cannot hear sounds played in the virtual machine.
298 By default the sound is muted. To enable playback launch the mixer applet by
299 clicking on the mixer icon in the task bar. Unmute the master volume control.
300 Now click on the "Volume control" to load the channel mixer dialog. Unmute
301 the "Master" and "PCM" channels and raise the volume as desired. You should
302 now be able to hear sounds played within the virtual machines through your
303 host computer's speakers.
305 I have upgraded VirtualBox from 3.x series to 4.x, and my VM lost
306 mounted host directories.
308 NeuroDebian VMs prior 6.0.3 were shipped with guest additions from
309 3.x series of VirtualBox and some initial versions of VirtualBox in
310 4.x series have failed to mount host directories properly.
311 VirtualBox 4.0.8 seems to work fine with guest additions from 3.x
312 series. If you nevertheless want to upgrade guest additions within
313 NeuroDebian VM, please rebuild the version available from the
316 sudo apt-get install -y linux-headers-2.6-amd64 # or -686 for 32bit
317 sudo apt-get install -y -t squeeze-backports virtualbox-ose-guest-dkms \
318 virtualbox-ose-guest-utils virtualbox-ose-guest-x11
322 .. include:: link_names.txt