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