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