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