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