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 7.0 (wheezy)`_ with a
  21 XFCE4_ 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
  39 Installation
  40 ~~~~~~~~~~~~
  41
  42 The following instructions demonstrate how to install the NeuroDebian virtual
  43 machine -- here shown exemplary for Mac OS X, but the procedure is virtually
  44 identical on a Windows box. There is also a video tutorial at coffee break
  45 length. `[Virtual machine setup video tutorial]
  46 <http://www.youtube.com/watch?v=eqfjKV5XaTE>`_.
  47
  48 If you don't have t already, first download and install a recent version of
  49 VirtualBox_. VirtualBox is a virtualization software that is freely available
  50 for Windows, MacOS X, Solaris, and Linux. VirtualBox comes with a comprehensive
  51 manual that should answer potential questions regarding installation and
  52 maintenance.
  53
  54 .. _VirtualBox: http://www.virtualbox.org
  55
  56 Obtain the most recent version of the NeuroDebian virtual machine by visiting
  57 http://neuro.debian.net and selecting your operating system and a download
  58 server on the frontpage.
  59
  60 Start VirtualBox and select "Import Appliance" from the file menu.
  61
  62 .. image:: pics/vm_import_app.jpg
  63
  64 The next dialog will ask you to choose a virtual machine. Please navigate to the
  65 extracted NeuroDebian download and select the `.ova` (or extracted
  66 `.ovf` for older appliances shipped as `.zip`) file.
  67
  68 .. image:: pics/vm_import_wizard.jpg
  69
  70 You can finish importing of NeuroDebian by clicking on *next* a couple of
  71 times.  There is no need to change anything, as we will get through the
  72 settings in a second.  Importing of the virtual machine will take a short
  73 while, as it is distributed in a compressed format that now gets extracted
  74 (total extracted size about 2 GB).  Once imported, the NeuroDebian virtual
  75 machine will appear in the list of available machines. Do **not** start it yet,
  76 but select NeuroDebian and hit the *Settings* button. In the following dialog
  77 you'll have a chance to configure the machine. You can assign the amount of RAM
  78 that should be made available to it (for serious fMRI data processing, please
  79 allow at least 2 GB). If you have a recent computer with multiple CPU cores,
  80 you can also decide how many cores should be used by the virtual machine.
  81
  82 .. image:: pics/vm_add_host_folder.jpg
  83
  84 However, most important is the *Shared Folders* setup. Shared folders allow the
  85 virtual machine to access the local harddrive of the host computer. This is an
  86 easy way to access data on the computer without duplicating it or using the
  87 network to access it. The virtual machine is preconfigured to access a shared
  88 folder named labeled "host".  Click on the *add* button to select a folder that
  89 shall be accessible by the machine (e.g. your home directory) and put "host" as
  90 the folder name and mark it to be auto-mounted. Note, the folder name is simply a label. Your directory will
  91 not be renamed.
  92
  93 .. image:: pics/vm_host_folder.jpg
  94
  95 If you have a large screen you should increase the display memory to
  96 32 MB in the *Display* settings.  Also you might like to enable the
  97 support for 3D Acceleration
  98
  99 .. image:: pics/vm_settings_display.jpg
 100
 101 Finally, close the settings dialog. You have now completed the setup, and you
 102 can start the virtual machine by hitting the *Start* button. A new window will
 103 appear showing the boot process. After a short while the NeuroDebian desktop
 104 will appear, and a setup wizard will guide your through the final steps of the
 105 configuration. You can now explore the system. The virtual machine is connected
 106 with your host computer, and shares its Internet connection. Via this
 107 connection you can update the contained software packages at any time.
 108
 109 .. image:: pics/vm_settings.jpg
 110
 111 The virtual machine logs yourself in automatically. This is the default account:
 112
 113 :user: brain
 114 :password: neurodebian
 115
 116 :root password: neurodebian
 117
 118 In most cases you should not be forced to type the password, because ``sudo``
 119 is configured to work without it.
 120
 121 .. note::
 122
 123   For increased security you might want to change the default password. You can
 124   do so by opening a terminal window and running the ``passwd`` command.
 125
 126
 127 Working with the virtual machine
 128 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 129
 130 The NeuroDebian virtual machine has very low maintenance demands. We have
 131 prepared a short video demo that shows most typical procedures that you will
 132 probably perform while working with NeuroDebian inside a virtual machine:
 133 use the virtual machine in full-screen and seamless mode, shared folder access,
 134 software installation, as well as suspending and resuming the
 135 virtual machine. `[Virtual machine handling video tutorial]
 136 <http://www.youtube.com/watch?v=OV7fYSEoOeQ>`_
 137
 138
 139 .. _chap_vm_troubleshooting:
 140
 141 Troubleshooting
 142 ~~~~~~~~~~~~~~~
 143
 144 .. container:: foldup
 145
 146   .. container:: expandinstructions
 147
 148      Click on an item to expand it
 149
 150   Updating the VM or installing new packages doesn't work
 151     The VM uses as service that tries to figure out the best/closest package
 152     repository for you. In some network environments this service might not work
 153     well, or not at all. To check if this is a problem, you can modify the
 154     respective configuration by hand. Edit ``/etc/apt/sources.list`` (you need
 155     to use ``sudo`` for that) and replace the package repository URL with a
 156     mirror close to you. A comprehensive list of mirrors is available at:
 157     http://www.debian.org/mirror/list
 158
 159     Pick one and replace all ``geomirror.debian.net`` URLs with the new mirror
 160     URL. For example, in Canada you might want to change::
 161
 162       deb http://i386-geomirror.debian.net/debian squeeze main non-free contrib
 163
 164     to::
 165
 166       deb http://ftp.ca.debian.org/debian/ squeeze main non-free contrib
 167
 168     Only modify lines that refer to ``geomirror`` (all of them), but do **not**
 169     modify entries for ``security.debian.org``.
 170
 171   Our proxy setup at work prevents APT from downloading packages
 172     APT needs to be told how to access the proxy. Talk to your local sysadmin
 173     and ask for the proxy's address (maybe a username and password too), as well
 174     as the ports for HTTP and FTP proxies. With this information add the
 175     following lines in the file, /etc/apt/apt.conf.d/80proxy. This will ensure
 176     that after an upgrade changes won't be lost::
 177
 178       Acquire::http::proxy "http://<username>:<password>@<proxy>:<port>/";
 179       Acquire::ftp::proxy "ftp://<username>:<password>@<proxy>:<port>/";
 180       Acquire::https::proxy "https://<username>:<password>@<proxy>:<port>/";
 181
 182   I cannot hear sounds played in the virtual machine
 183     By default the sound is muted. To enable playback launch the mixer applet by
 184     clicking on the mixer icon in the task bar. Unmute the master volume
 185     control. Now click on the "Volume control" to load the channel mixer dialog.
 186     Unmute the "Master" and "PCM" channels and raise the volume as desired. You
 187     should now be able to hear sounds played within the virtual machines through
 188     your host computer's speakers.
 189
 190   My VM lost mounted host directories after upgrading from VirtualBox from 3.x to 4.x
 191     NeuroDebian VMs prior 6.0.3 were shipped with guest additions from
 192     3.x series of VirtualBox and some initial versions of VirtualBox in
 193     4.x series have failed to mount host directories properly.
 194     VirtualBox 4.0.8 seems to work fine with guest additions from 3.x
 195     series.  If you nevertheless want to upgrade guest additions within
 196     NeuroDebian VM, please rebuild the version available from the
 197     backports::
 198
 199       sudo apt-get install -y linux-headers-2.6-`dpkg --print-architecture`
 200       sudo apt-get install -y -t squeeze-backports virtualbox-ose-guest-dkms \
 201            virtualbox-ose-guest-utils  virtualbox-ose-guest-x11
 202
 203     and reboot VM.
 204
 205   My VM lost mounted host directories, and display auto-resizing  after upgrade
 206     NeuroDebian VMs ship without Linux kernel headers pre-installed to
 207     minimize distribution/running footprint for one time throw-away
 208     usages of the VM.  To install headers package(s) just run
 209
 210       sudo apt-get install -y linux-headers-`dpkg --print-architecture`
 211
 212     and reboot VM.
 213
 214   I am still running an older VirtualBox 3.x
 215     Download one of the image files listed below. These older releases
 216     are distributed as a `zip` file. Please extract all files from the
 217     `.zip` file, using appropriate software for your operating system.
 218
 219     * `NeuroDebian 6.0.2 image (32bit)
 220       <http://neuro.debian.net/debian/vm/neurodebian_6.0.2_i386.zip>`_ [~545MB]
 221
 222     * `NeuroDebian 6.0.2 image (64bit)
 223       <http://neuro.debian.net/debian/vm/neurodebian_6.0.2_amd64.zip>`_ [~560MB]
 224
 225
 226 What has changed
 227 ----------------
 228
 229 .. container:: foldup
 230
 231   .. container:: expandinstructions
 232
 233      Click on an item to expand it
 234
 235   7.8.0 -- 2 Feb 2015
 236     * VM appliance based on the updated wheezy point release 7.8.0.
 237       Should resolve problems with upgrades of the guest additions.
 238
 239   7.4.20140423 -- 24 Apr 2014
 240     * VM appliance based on the updated wheezy point release 7.4.
 241       Should resolve problems with upgrades of the guest additions.
 242       See http://neuro.debian.net/faq.html#comment-1351846812
 243
 244   7.4.0 -- 28 Feb 2014
 245     * VM appliance based on the official wheezy point release 7.4.
 246
 247   7.2.0 -- 03 Nov 2013
 248     * VM appliance based on the official wheezy point release 7.2.
 249     * Ships with updated neurodebian-* packages:
 250       - installs ipython notebook and qtconsole for "Scientific Python"
 251                 and "PyMVPA tutorial" welcome wizard choices.
 252
 253   7.0.0 -- 15 May 2013
 254     * VM appliance based on the official wheezy release.
 255     * Uses xfce4-terminal by default (instead of urxvt/rxvt-unicode as
 256       in beta-releases)
 257
 258   6.999.b4.20130421 -- 22 Apr 2013
 259     * Refreshed VM appliance to avoid lengthy initial upgrade
 260
 261   6.999.b4.20121231 -- 31 Dec 2012
 262     * Based on beta 4 release of debian-installer_ for wheezy
 263     * Comes with XFCE4_ instead of GNOME_
 264
 265   6.0.6 -- 01 Oct 2012
 266     * Updated core system to Debian squeeze 6.0.6
 267
 268   6.0.5 -- 10 Nov 2011
 269     * Updated core system to Debian squeeze 6.0.3
 270     * Updated shipped virtualbox-ose guest-utils and guest-x11 to 4.0.10
 271
 272       - ``~/host`` is now symlinked to correct path ``/media/sf_host``
 273       - ``brain`` user is added to ``vboxsf`` group so mounted host
 274         directories should become readily available
 275
 276     * Root partition size and swap space got doubled in size (40GB
 277       and 2GB correspondingly).  Space is allocated dynamically so
 278       the actual size of the virtual drive should not grow unless
 279       you use it
 280
 281   6.0.4 -- 13 Jun 2011
 282     * Updated shipped virtualbox-ose guest-utils and guest-x11 to 4.0.4
 283
 284   6.0.3 -- 12 Jun 2011 [Superseded in the archive by 6.0.4]
 285     * Updated to Squeeze 6.0.1
 286     * Updated VirtualBox guest additions to 4.0.4 from backports.debian.org
 287     * Appliance is available as a single file (.ova) ready for the import
 288
 289   6.0.2 -- 08 Feb 2011
 290     * Minor update
 291
 292   6.0.1 -- 01 Dec 2010
 293     * Minor update
 294
 295 .. include:: link_names.txt