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