sphinx/vm.rst

   1 .. _chap_vm:
   2
   3 NeuroDebian Virtual Machine
   4 ===========================
   5
   6 .. quotes::
   7    :random: 1
   8    :tags: vm
   9
  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_).
  16
  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
  22
  23
  24 Downloads
  25 ---------
  26
  27 * `NeuroDebian 6.0.4 image (32bit)
  28   <http://neuro.debian.net/debian/vm/NeuroDebian_6.0.4_i386.ova>`_ [~558MB]
  29
  30   *This image should work on virtually all systems that are supported by*
  31   VirtualBox_ *and can be used whenever the, otherwise preferable, 64bit image
  32   is not compatible with a host machine.*
  33
  34 * `NeuroDebian 6.0.4 image (64bit)
  35   <http://neuro.debian.net/debian/vm/NeuroDebian_6.0.4_amd64.ova>`_ [~573MB]
  36
  37   *This image only works on 64bit host machines with active hardware
  38   virtualization support. The should include all recent Apple hardware and most
  39   64bit Windows systems.*
  40
  41 Virtual appliances above carry guest additions for 4.x series of the
  42 VirtualBox. If you still have VirtualBox 3.x, use previous 6.0.2
  43 virtual appliances:
  44
  45 * `NeuroDebian 6.0.2 image (32bit)
  46   <http://neuro.debian.net/debian/vm/neurodebian_6.0.2_i386.zip>`_ [~545MB]
  47
  48 * `NeuroDebian 6.0.2 image (64bit)
  49   <http://neuro.debian.net/debian/vm/neurodebian_6.0.2_amd64.zip>`_ [~560MB]
  50
  51 .. note::
  52
  53   You can verify that you have downloaded archives correctly using
  54   `md5sums -c MD5SUMS
  55   <http://neuro.debian.net/debian/vm/MD5SUMS>`_ . You can also verify
  56   the authenticity of the `MD5SUMS
  57   <http://neuro.debian.net/debian/vm/MD5SUMS>`_ itself using `gpg
  58   --verify MD5SUMS.gpg
  59   <http://neuro.debian.net/debian/vm/MD5SUMS.gpg>`_ signed with
  60   NeuroDebian archive key.
  61
  62 * `VirtualBox download page <http://www.virtualbox.org/wiki/Downloads>`_ (Windows, Linux, Mac,
  63   Solaris)
  64
  65   *This webpage offers installers of the VirtualBox application, as well as the
  66   documentation.*
  67
  68 Changes
  69 -------
  70
  71 6.0.4 -- 13 Jun 2011
  72
  73       * Updated shipped virtualbox-ose guest-utils and guest-x11 to 4.0.4
  74
  75 6.0.3 -- 12 Jun 2011 [Superseded in the archive by 6.0.4]
  76
  77       * Updated to Squeeze 6.0.1
  78       * Updated VirtualBox guest additions to 4.0.4 from backports.debian.org
  79       * Appliance is available as a single file (.ova) ready for the import
  80
  81 6.0.2 -- 08 Feb 2011
  82
  83 6.0.1 -- 01 Dec 2010
  84
  85 Documentation
  86 -------------
  87
  88 The virtual machine contains an installation of `Debian 6.0 (squeeze)`_ with a
  89 GNOME_ desktop environment. All installed software comes from standard Debian
  90 packages, or prospective Debian packages from NeuroDebian. This means that all
  91 contained software is readily available for any system running a Debian
  92 operating system (or a recent Ubuntu release). The virtual machine can be seen
  93 as a showcase of what Debian for neuroscience research feels like. Moreover,
  94 once downloaded this virtual machine can be kept up to date, just as any other
  95 Debian installation. Using convenient graphical package management tools users
  96 will benefit from security bug fixes provided by the Debian project for the
  97 whole operating system, as well as from software updates for
  98 neuroscience-related packages.
  99
 100 .. _Debian 6.0 (squeeze): http://www.debian.org/releases/squeeze
 101 .. _GNOME: http://www.gnome.org/
 102
 103
 104 Installation
 105 ~~~~~~~~~~~~
 106
 107 The following video shows how to get the NeuroDebian virtual machine running
 108 on your machine. The installation is shown for Mac OS X. It should, however, be
 109 very similar on a Windows box. If you cannot watch the video, please take a
 110 look at the written instructions below.
 111
 112 .. raw:: html
 113
 114   <iframe title="YouTube video player"
 115           class="youtube-player"
 116           type="text/html"
 117           width="640"
 118           height="375"
 119           src="http://www.youtube.com/embed/eqfjKV5XaTE?hd=1"
 120           frameborder="0"></iframe>
 121
 122 First download and install a recent version of VirtualBox_. VirtualBox is a
 123 virtualization software that is freely available for Windows, MacOS X, Solaris,
 124 and Linux. VirtualBox comes with a comprehensive manual that should answer
 125 potential questions regarding installation and maintenance.
 126
 127 .. _VirtualBox: http://www.virtualbox.org
 128
 129 Next, download the most recent version of the NeuroDebian virtual machine from
 130 the Downloads_ section. The machine is distributed as a zip file. Please
 131 extract this file, using appropriate software for your operating system.
 132 Once extracted, start VirtualBox and select "Import Appliance" from the file
 133 menu.
 134
 135 .. image:: pics/vm_import_app.jpg
 136
 137 The next dialog will ask you to choose a virtual machine. Please navigate to the
 138 extracted NeuroDebian download and select the `.ovf` file.
 139
 140 .. image:: pics/vm_import_wizard.jpg
 141
 142 You can finish importing of NeuroDebian by clicking on *next* a couple of
 143 times.  There is no need to change anything, as we will get through the
 144 settings in a second.  Importing of the virtual machine will take a short
 145 while, as it is distributed in a compressed format that now gets extracted
 146 (total extracted size about 2 GB).  Once imported, the NeuroDebian virtual
 147 machine will appear in the list of available machines. Do **not** start it yet,
 148 but select NeuroDebian and hit the *Settings* button. In the following dialog
 149 you'll have a chance to configure the machine. You can assign the amount of RAM
 150 that should be made available to it (for serious fMRI data processing, please
 151 allow at least 2 GB). If you have a recent computer with multiple CPU cores,
 152 you can also decide how many cores should be used by the virtual machine. If
 153 you have a large screen you should increase the display memory to 32 MB in the
 154 *Display* settings.
 155
 156 .. image:: pics/vm_add_host_folder.jpg
 157
 158 However, most important is the *Shared Folders* setup. Shared folders allow the
 159 virtual machine to access the local harddrive of the host computer. This is an
 160 easy way to access data on the computer without duplicating it or using the
 161 network to access it. The virtual machine is preconfigured to access a shared
 162 folder named labeled "host".  Click on the *add* button to select a folder that
 163 shall be accessible by the machine (e.g. your home directory) and put "host" as
 164 the folder name. Note, the folder name is simply a label. Your directory will
 165 not be renamed.
 166
 167 .. image:: pics/vm_host_folder.jpg
 168
 169 Finally, close the settings dialog. You have now completed the setup, and you
 170 can start the virtual machine by hitting the *Start* button. A new window will
 171 appear showing the boot process. After a short while the NeuroDebian desktop
 172 will appear, and a setup wizard will guide your through the final steps of the
 173 configuration. You can now explore the system. The virtual machine is connected
 174 with your host computer, and shares its Internet connection. Via this
 175 connection you can update the contained software packages at any time.
 176
 177 .. image:: pics/vm_settings.jpg
 178
 179 The virtual machine logs yourself in automatically. The name of the virtual
 180 machine user is `brain` and the password is `neurodebian`. The *root* password
 181 is also `neurodebian`. In most cases, however, you should not be forced to type
 182 the password, since `sudo` is configured to work without it.
 183
 184 .. note::
 185
 186   For increased security you might want to change the default password. You can
 187   do so by opening a terminal window and running the ``passwd`` command.
 188
 189
 190 Working with the virtual machine
 191 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 192
 193 The next video is a demonstration of some basic desktop integration features.
 194 It shows how to use the virtual machine in full-screen and seamless mode, shared
 195 folder access, software installation, as well as suspending and resuming the
 196 virtual machine.
 197
 198 .. raw:: html
 199
 200   <iframe title="YouTube video player"
 201           class="youtube-player"
 202           type="text/html"
 203           width="640"
 204           height="375"
 205           src="http://www.youtube.com/embed/OV7fYSEoOeQ?hd=1"
 206           frameborder="0"></iframe>
 207
 208
 209 .. _chap_vm_troubleshooting:
 210
 211 Troubleshooting
 212 ~~~~~~~~~~~~~~~
 213
 214 Updating the VM or installing new packages doesn't work.
 215
 216   The VM uses as service that tries to figure out the best/closest package
 217   repository for you. In some network environments this service might not work
 218   well, or not at all. To check if this is a problem, you can modify the
 219   respective configuration by hand. Edit ``/etc/apt/sources.list`` (you need to
 220   use ``sudo`` for that) and replace the package repository URL with a mirror
 221   close to you. A comprehensive list of mirrors is available at:
 222   http://www.debian.org/mirror/list
 223
 224   Pick one and replace all ``geomirror.debian.net`` URLs with the new mirror
 225   URL. For example, in Canada you might want to change::
 226
 227     deb http://i386-geomirror.debian.net/debian squeeze main non-free contrib
 228
 229   to::
 230
 231     deb http://ftp.ca.debian.org/debian/ squeeze main non-free contrib
 232
 233   Only modify lines that refer to ``geomirror`` (all of them), but do **not**
 234   modify entries for ``security.debian.org``.
 235
 236 I cannot hear sounds played in the virtual machine.
 237
 238   By default the sound is muted. To enable playback launch the mixer applet by
 239   clicking on the mixer icon in the task bar. Unmute the master volume control.
 240   Now click on the "Volume control" to load the channel mixer dialog. Unmute
 241   the "Master" and "PCM" channels and raise the volume as desired. You should
 242   now be able to hear sounds played within the virtual machines through your
 243   host computer's speakers.
 244
 245 I have upgraded VirtualBox from 3.x series to 4.x, and my VM lost
 246 mounted host directories.
 247
 248   NeuroDebian VMs prior 6.0.3 were shipped with guest additions from
 249   3.x series of VirtualBox and some initial versions of VirtualBox in
 250   4.x series have failed to mount host directories properly.
 251   VirtualBox 4.0.8 seems to work fine with guest additions from 3.x
 252   series.  If you nevertheless want to upgrade guest additions within
 253   NeuroDebian VM, please rebuild the version available from the
 254   backports::
 255
 256     sudo apt-get install -y linux-headers-2.6-amd64 # or -686 for 32bit
 257     sudo apt-get install -y -t squeeze-backports virtualbox-ose-guest-kdms \
 258          virtualbox-ose-guest-utils  virtualbox-ose-guest-x11
 259
 260   and reboot VM.