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