sphinx/vm.rst

   1 .. _chap_vm:
   2
   3 NeuroDebian Virtual Machine
   4 ===========================
   5
   6 `Installation`_ | `Working with the virtual machine`_ | `Troubleshooting`_ |
   7 `What has changed`_
   8
   9 .. quotes::
  10    :random: 1
  11    :tags: vm
  12
  13 For all systems running a non-Debian-based operation system, such as MS Windows
  14 or Mac OS X, we offer a `virtual machine`_ that can be equipped with a large
  15 variety of neuroscience software with just a few mouse clicks (e.g. AFNI_,
  16 FSL_, PyMVPA_).
  17
  18 .. _virtual machine: http://en.wikipedia.org/wiki/Virtual_machine
  19 .. _AFNI: http://afni.nimh.nih.gov/afni/
  20 .. _Caret: http://brainvis.wustl.edu/wiki/index.php/Caret:About
  21 .. _FSL: http://www.fmrib.ox.ac.uk/fsl/
  22 .. _PyMVPA: http://www.pymvpa.org
  23
  24 The virtual machine contains an installation of `Debian 6.0 (squeeze)`_ with a
  25 GNOME_ desktop environment. All installed software comes from standard Debian
  26 packages, or prospective Debian packages from NeuroDebian. The virtual machine
  27 can be seen as a showcase of what Debian for neuroscience research feels like.
  28 Once downloaded this virtual machine can be kept up to date, just as any other
  29 Debian installation. Using convenient graphical package management tools users
  30 will benefit from security bug fixes provided by the Debian project for the
  31 whole operating system, as well as from software updates for
  32 neuroscience-related packages.
  33
  34 Even on Debian-based systems this virtual machine is an excellent way to
  35 maintain an analysis environment that remains identical throughout the lifetime
  36 of a study and that can be archived alongside acquired data and publications.
  37 This is a much more practical way than freezing the entire software stack of a
  38 whole workstation, where it quickly becomes troublesome to combine the desire
  39 for latest research methodology for new studies and the need for stability for
  40 ongoing projects.
  41
  42 .. _Debian 6.0 (squeeze): http://www.debian.org/releases/squeeze
  43 .. _GNOME: http://www.gnome.org/
  44
  45
  46 Installation
  47 ~~~~~~~~~~~~
  48
  49 The following instructions demonstrate how to install the NeuroDebian virtual
  50 machine -- here shown exemplary for Mac OS X, but the procedure is virtually
  51 identical on a Windows box. There is also a video tutorial at coffee break
  52 length. `[Virtual machine setup video tutorial]
  53 <http://www.youtube.com/watch?v=eqfjKV5XaTE>`_.
  54
  55 If you don't have t already, first download and install a recent version of
  56 VirtualBox_. VirtualBox is a virtualization software that is freely available
  57 for Windows, MacOS X, Solaris, and Linux. VirtualBox comes with a comprehensive
  58 manual that should answer potential questions regarding installation and
  59 maintenance.
  60
  61 .. _VirtualBox: http://www.virtualbox.org
  62
  63 Obtain the most recent version of the NeuroDebian virtual machine by visiting
  64 http://neuro.debian.net and selecting your operating system and a download
  65 server on the frontpage.
  66
  67 Start VirtualBox and select "Import Appliance" from the file menu.
  68
  69 .. image:: pics/vm_import_app.jpg
  70
  71 The next dialog will ask you to choose a virtual machine. Please navigate to the
  72 extracted NeuroDebian download and select the `.ova` (or extracted
  73 `.ovf` for older appliances shipped as `.zip`) file.
  74
  75 .. image:: pics/vm_import_wizard.jpg
  76
  77 You can finish importing of NeuroDebian by clicking on *next* a couple of
  78 times.  There is no need to change anything, as we will get through the
  79 settings in a second.  Importing of the virtual machine will take a short
  80 while, as it is distributed in a compressed format that now gets extracted
  81 (total extracted size about 2 GB).  Once imported, the NeuroDebian virtual
  82 machine will appear in the list of available machines. Do **not** start it yet,
  83 but select NeuroDebian and hit the *Settings* button. In the following dialog
  84 you'll have a chance to configure the machine. You can assign the amount of RAM
  85 that should be made available to it (for serious fMRI data processing, please
  86 allow at least 2 GB). If you have a recent computer with multiple CPU cores,
  87 you can also decide how many cores should be used by the virtual machine.
  88
  89 .. image:: pics/vm_add_host_folder.jpg
  90
  91 However, most important is the *Shared Folders* setup. Shared folders allow the
  92 virtual machine to access the local harddrive of the host computer. This is an
  93 easy way to access data on the computer without duplicating it or using the
  94 network to access it. The virtual machine is preconfigured to access a shared
  95 folder named labeled "host".  Click on the *add* button to select a folder that
  96 shall be accessible by the machine (e.g. your home directory) and put "host" as
  97 the folder name and mark it to be auto-mounted. Note, the folder name is simply a label. Your directory will
  98 not be renamed.
  99
 100 .. image:: pics/vm_host_folder.jpg
 101
 102 If you have a large screen you should increase the display memory to
 103 32 MB in the *Display* settings.  Also you might like to enable the
 104 support for 3D Acceleration
 105
 106 .. image:: pics/vm_settings_display.jpg
 107
 108 Finally, close the settings dialog. You have now completed the setup, and you
 109 can start the virtual machine by hitting the *Start* button. A new window will
 110 appear showing the boot process. After a short while the NeuroDebian desktop
 111 will appear, and a setup wizard will guide your through the final steps of the
 112 configuration. You can now explore the system. The virtual machine is connected
 113 with your host computer, and shares its Internet connection. Via this
 114 connection you can update the contained software packages at any time.
 115
 116 .. image:: pics/vm_settings.jpg
 117
 118 The virtual machine logs yourself in automatically. This is the default account:
 119
 120 :user: brain
 121 :password: neurodebian
 122
 123 :root password: neurodebian
 124
 125 In most cases you should not be forced to type the password, because ``sudo``
 126 is configured to work without it.
 127
 128 .. note::
 129
 130   For increased security you might want to change the default password. You can
 131   do so by opening a terminal window and running the ``passwd`` command.
 132
 133
 134 Working with the virtual machine
 135 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 136
 137 The NeuroDebian virtual machine has very low maintenance demands. We have
 138 prepared a short video demo that shows most typical procedures that you will
 139 probably perform while working with NeuroDebian inside a virtual machine:
 140 use the virtual machine in full-screen and seamless mode, shared folder access,
 141 software installation, as well as suspending and resuming the
 142 virtual machine. `[Virtual machine handling video tutorial]
 143 <http://www.youtube.com/watch?v=OV7fYSEoOeQ>`_
 144
 145
 146 .. _chap_vm_troubleshooting:
 147
 148 Troubleshooting
 149 ~~~~~~~~~~~~~~~
 150
 151 .. raw:: html
 152
 153   <div class="expandinstructions">Click on an item to expand it</div>
 154
 155 Updating the VM or installing new packages doesn't work
 156   The VM uses as service that tries to figure out the best/closest package
 157   repository for you. In some network environments this service might not work
 158   well, or not at all. To check if this is a problem, you can modify the
 159   respective configuration by hand. Edit ``/etc/apt/sources.list`` (you need to
 160   use ``sudo`` for that) and replace the package repository URL with a mirror
 161   close to you. A comprehensive list of mirrors is available at:
 162   http://www.debian.org/mirror/list
 163
 164   Pick one and replace all ``geomirror.debian.net`` URLs with the new mirror
 165   URL. For example, in Canada you might want to change::
 166
 167     deb http://i386-geomirror.debian.net/debian squeeze main non-free contrib
 168
 169   to::
 170
 171     deb http://ftp.ca.debian.org/debian/ squeeze main non-free contrib
 172
 173   Only modify lines that refer to ``geomirror`` (all of them), but do **not**
 174   modify entries for ``security.debian.org``.
 175
 176 Our proxy setup at work prevents APT from downloading packages
 177   APT needs to be told how to access the proxy. Talk to your local sysadmin
 178   and ask for the proxy's address (maybe a username and password too), as well
 179   as the ports for HTTP and FTP proxies. With this information add the following
 180   lines in the file, /etc/apt/apt.conf.d/80proxy. This will ensure that after an
 181   upgrade changes won't be lost::
 182
 183     Acquire::http::proxy "http://<username>:<password>@<proxy>:<port>/";
 184     Acquire::ftp::proxy "ftp://<username>:<password>@<proxy>:<port>/";
 185     Acquire::https::proxy "https://<username>:<password>@<proxy>:<port>/";
 186
 187 I cannot hear sounds played in the virtual machine
 188   By default the sound is muted. To enable playback launch the mixer applet by
 189   clicking on the mixer icon in the task bar. Unmute the master volume control.
 190   Now click on the "Volume control" to load the channel mixer dialog. Unmute
 191   the "Master" and "PCM" channels and raise the volume as desired. You should
 192   now be able to hear sounds played within the virtual machines through your
 193   host computer's speakers.
 194
 195 My VM lost mounted host directories after upgrading from VirtualBox from 3.x to 4.x
 196   NeuroDebian VMs prior 6.0.3 were shipped with guest additions from
 197   3.x series of VirtualBox and some initial versions of VirtualBox in
 198   4.x series have failed to mount host directories properly.
 199   VirtualBox 4.0.8 seems to work fine with guest additions from 3.x
 200   series.  If you nevertheless want to upgrade guest additions within
 201   NeuroDebian VM, please rebuild the version available from the
 202   backports::
 203
 204     sudo apt-get install -y linux-headers-2.6-amd64 # or -686 for 32bit
 205     sudo apt-get install -y -t squeeze-backports virtualbox-ose-guest-dkms \
 206          virtualbox-ose-guest-utils  virtualbox-ose-guest-x11
 207
 208   and reboot VM.
 209
 210
 211 What has changed
 212 ----------------
 213
 214 .. raw:: html
 215
 216   <div class="expandinstructions">Click on an item to expand it</div>
 217
 218 6.0.6 -- 01 Oct 2012
 219
 220   * Updated core system to Debian squeeze 6.0.6
 221
 222 6.0.5 -- 10 Nov 2011
 223   * Updated core system to Debian squeeze 6.0.3
 224   * Updated shipped virtualbox-ose guest-utils and guest-x11 to 4.0.10
 225
 226     - ``~/host`` is now symlinked to correct path ``/media/sf_host``
 227     - ``brain`` user is added to ``vboxsf`` group so mounted host
 228       directories should become readily available
 229
 230   * Root partition size and swap space got doubled in size (40GB
 231     and 2GB correspondingly).  Space is allocated dynamically so
 232     the actual size of the virtual drive should not grow unless
 233     you use it
 234
 235 6.0.4 -- 13 Jun 2011
 236   * Updated shipped virtualbox-ose guest-utils and guest-x11 to 4.0.4
 237
 238 6.0.3 -- 12 Jun 2011 [Superseded in the archive by 6.0.4]
 239   * Updated to Squeeze 6.0.1
 240   * Updated VirtualBox guest additions to 4.0.4 from backports.debian.org
 241   * Appliance is available as a single file (.ova) ready for the import
 242
 243 6.0.2 -- 08 Feb 2011
 244   * Minor update
 245
 246 6.0.1 -- 01 Dec 2010
 247   * Minor update