3 NeuroDebian Virtual Machine
4 ===========================
6 `Installation`_ | `Working with the virtual machine`_ | `Troubleshooting`_ |
13 For all systems running a non-Debian-based operation system, such as MS Windows
14 or Mac OS X, we offer a `virtual machine`_ that can be equipped with a large
15 variety of neuroscience software with just a few mouse clicks (e.g. AFNI_,
18 .. _virtual machine: http://en.wikipedia.org/wiki/Virtual_machine
19 .. _AFNI: http://afni.nimh.nih.gov/afni/
20 .. _Caret: http://brainvis.wustl.edu/wiki/index.php/Caret:About
21 .. _FSL: http://www.fmrib.ox.ac.uk/fsl/
22 .. _PyMVPA: http://www.pymvpa.org
24 The virtual machine contains an installation of `Debian 6.0 (squeeze)`_ with a
25 GNOME_ desktop environment. All installed software comes from standard Debian
26 packages, or prospective Debian packages from NeuroDebian. The virtual machine
27 can be seen as a showcase of what Debian for neuroscience research feels like.
28 Once downloaded this virtual machine can be kept up to date, just as any other
29 Debian installation. Using convenient graphical package management tools users
30 will benefit from security bug fixes provided by the Debian project for the
31 whole operating system, as well as from software updates for
32 neuroscience-related packages.
34 Even on Debian-based systems this virtual machine is an excellent way to
35 maintain an analysis environment that remains identical throughout the lifetime
36 of a study and that can be archived alongside acquired data and publications.
37 This is a much more practical way than freezing the entire software stack of a
38 whole workstation, where it quickly becomes troublesome to combine the desire
39 for latest research methodology for new studies and the need for stability for
42 .. _Debian 6.0 (squeeze): http://www.debian.org/releases/squeeze
43 .. _GNOME: http://www.gnome.org/
49 The following instructions demonstrate how to install the NeuroDebian virtual
50 machine -- here shown exemplary for Mac OS X, but the procedure is virtually
51 identical on a Windows box. There is also a video tutorial at coffee break
52 length. `[Virtual machine setup video tutorial]
53 <http://www.youtube.com/watch?v=eqfjKV5XaTE>`_.
55 If you don't have t already, first download and install a recent version of
56 VirtualBox_. VirtualBox is a virtualization software that is freely available
57 for Windows, MacOS X, Solaris, and Linux. VirtualBox comes with a comprehensive
58 manual that should answer potential questions regarding installation and
61 .. _VirtualBox: http://www.virtualbox.org
63 Obtain the most recent version of the NeuroDebian virtual machine by visiting
64 http://neuro.debian.net and selecting your operating system and a download
65 server on the frontpage.
67 Start VirtualBox and select "Import Appliance" from the file menu.
69 .. image:: pics/vm_import_app.jpg
71 The next dialog will ask you to choose a virtual machine. Please navigate to the
72 extracted NeuroDebian download and select the `.ova` (or extracted
73 `.ovf` for older appliances shipped as `.zip`) file.
75 .. image:: pics/vm_import_wizard.jpg
77 You can finish importing of NeuroDebian by clicking on *next* a couple of
78 times. There is no need to change anything, as we will get through the
79 settings in a second. Importing of the virtual machine will take a short
80 while, as it is distributed in a compressed format that now gets extracted
81 (total extracted size about 2 GB). Once imported, the NeuroDebian virtual
82 machine will appear in the list of available machines. Do **not** start it yet,
83 but select NeuroDebian and hit the *Settings* button. In the following dialog
84 you'll have a chance to configure the machine. You can assign the amount of RAM
85 that should be made available to it (for serious fMRI data processing, please
86 allow at least 2 GB). If you have a recent computer with multiple CPU cores,
87 you can also decide how many cores should be used by the virtual machine.
89 .. image:: pics/vm_add_host_folder.jpg
91 However, most important is the *Shared Folders* setup. Shared folders allow the
92 virtual machine to access the local harddrive of the host computer. This is an
93 easy way to access data on the computer without duplicating it or using the
94 network to access it. The virtual machine is preconfigured to access a shared
95 folder named labeled "host". Click on the *add* button to select a folder that
96 shall be accessible by the machine (e.g. your home directory) and put "host" as
97 the folder name and mark it to be auto-mounted. Note, the folder name is simply a label. Your directory will
100 .. image:: pics/vm_host_folder.jpg
102 If you have a large screen you should increase the display memory to
103 32 MB in the *Display* settings. Also you might like to enable the
104 support for 3D Acceleration
106 .. image:: pics/vm_settings_display.jpg
108 Finally, close the settings dialog. You have now completed the setup, and you
109 can start the virtual machine by hitting the *Start* button. A new window will
110 appear showing the boot process. After a short while the NeuroDebian desktop
111 will appear, and a setup wizard will guide your through the final steps of the
112 configuration. You can now explore the system. The virtual machine is connected
113 with your host computer, and shares its Internet connection. Via this
114 connection you can update the contained software packages at any time.
116 .. image:: pics/vm_settings.jpg
118 The virtual machine logs yourself in automatically. This is the default account:
121 :password: neurodebian
123 :root password: neurodebian
125 In most cases you should not be forced to type the password, because ``sudo``
126 is configured to work without it.
130 For increased security you might want to change the default password. You can
131 do so by opening a terminal window and running the ``passwd`` command.
134 Working with the virtual machine
135 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
137 The NeuroDebian virtual machine has very low maintenance demands. We have
138 prepared a short video demo that shows most typical procedures that you will
139 probably perform while working with NeuroDebian inside a virtual machine:
140 use the virtual machine in full-screen and seamless mode, shared folder access,
141 software installation, as well as suspending and resuming the
142 virtual machine. `[Virtual machine handling video tutorial]
143 <http://www.youtube.com/watch?v=OV7fYSEoOeQ>`_
146 .. _chap_vm_troubleshooting:
151 .. container:: foldup
153 .. container:: expandinstructions
155 Click on an item to expand it
157 Updating the VM or installing new packages doesn't work
158 The VM uses as service that tries to figure out the best/closest package
159 repository for you. In some network environments this service might not work
160 well, or not at all. To check if this is a problem, you can modify the
161 respective configuration by hand. Edit ``/etc/apt/sources.list`` (you need
162 to use ``sudo`` for that) and replace the package repository URL with a
163 mirror close to you. A comprehensive list of mirrors is available at:
164 http://www.debian.org/mirror/list
166 Pick one and replace all ``geomirror.debian.net`` URLs with the new mirror
167 URL. For example, in Canada you might want to change::
169 deb http://i386-geomirror.debian.net/debian squeeze main non-free contrib
173 deb http://ftp.ca.debian.org/debian/ squeeze main non-free contrib
175 Only modify lines that refer to ``geomirror`` (all of them), but do **not**
176 modify entries for ``security.debian.org``.
178 Our proxy setup at work prevents APT from downloading packages
179 APT needs to be told how to access the proxy. Talk to your local sysadmin
180 and ask for the proxy's address (maybe a username and password too), as well
181 as the ports for HTTP and FTP proxies. With this information add the
182 following lines in the file, /etc/apt/apt.conf.d/80proxy. This will ensure
183 that after an upgrade changes won't be lost::
185 Acquire::http::proxy "http://<username>:<password>@<proxy>:<port>/";
186 Acquire::ftp::proxy "ftp://<username>:<password>@<proxy>:<port>/";
187 Acquire::https::proxy "https://<username>:<password>@<proxy>:<port>/";
189 I cannot hear sounds played in the virtual machine
190 By default the sound is muted. To enable playback launch the mixer applet by
191 clicking on the mixer icon in the task bar. Unmute the master volume
192 control. Now click on the "Volume control" to load the channel mixer dialog.
193 Unmute the "Master" and "PCM" channels and raise the volume as desired. You
194 should now be able to hear sounds played within the virtual machines through
195 your host computer's speakers.
197 My VM lost mounted host directories after upgrading from VirtualBox from 3.x to 4.x
198 NeuroDebian VMs prior 6.0.3 were shipped with guest additions from
199 3.x series of VirtualBox and some initial versions of VirtualBox in
200 4.x series have failed to mount host directories properly.
201 VirtualBox 4.0.8 seems to work fine with guest additions from 3.x
202 series. If you nevertheless want to upgrade guest additions within
203 NeuroDebian VM, please rebuild the version available from the
206 sudo apt-get install -y linux-headers-2.6-amd64 # or -686 for 32bit
207 sudo apt-get install -y -t squeeze-backports virtualbox-ose-guest-dkms \
208 virtualbox-ose-guest-utils virtualbox-ose-guest-x11
216 .. container:: foldup
218 .. container:: expandinstructions
220 Click on an item to expand it
223 * Updated core system to Debian squeeze 6.0.6
226 * Updated core system to Debian squeeze 6.0.3
227 * Updated shipped virtualbox-ose guest-utils and guest-x11 to 4.0.10
229 - ``~/host`` is now symlinked to correct path ``/media/sf_host``
230 - ``brain`` user is added to ``vboxsf`` group so mounted host
231 directories should become readily available
233 * Root partition size and swap space got doubled in size (40GB
234 and 2GB correspondingly). Space is allocated dynamically so
235 the actual size of the virtual drive should not grow unless
239 * Updated shipped virtualbox-ose guest-utils and guest-x11 to 4.0.4
241 6.0.3 -- 12 Jun 2011 [Superseded in the archive by 6.0.4]
242 * Updated to Squeeze 6.0.1
243 * Updated VirtualBox guest additions to 4.0.4 from backports.debian.org
244 * Appliance is available as a single file (.ova) ready for the import