Skip to end of metadata
Go to start of metadata


This document explains how to jump-start the analysis environment on a laptop using a virtual machine (VM) image. The recipe would work as well for any other hardware (desktop, server). In this document we're exploring a technology based on Oracle VM VirtualBox. The main benefit of the software is that it's stable and it's free. Besides, it's easy to set up. The software is available for all popular platforms, including Linux (all distributions), Windows 7/8, MacOS, or Solaris. However a similar approach would work as well for other hypervisors, such as Parallels, VMware, etc. They all would recognize a format of the packaged VM images which we're exporting here.

If you run into problems while following the instructions below, please check the problems section below.

Preparing your computer to host virtual images

The first step before downloading anything is to make sure your CPU has a hardware support for the virtualization technology. This is known as VT-x on Intel CPUs or AMD-V on the AMD CPUs. All modern CPUs built over the last 5 years should have it. But you would better check if the one you have. Each operating system has the corresponding tool which would tell you this information. Here is how this can be done on some of the systems:


% cat /proc/cpuinfo | grep 'model name'
model name      : Intel(R) Xeon(R) CPU           E5520  @ 2.27GHz

Windows 7 :

Windows Vista/8:


Lookup your CPU model on a Web site of the CPU manufacturer. Normally, all Intel CPU's after Core 2 Duo will support the virtualization.

The next step is to make sure that the virtualization technology is enabled in the machine's BIOS. In many cases it may be disabled. Unfortunately, we can't give you any specific advise on how to do so for your particular computer because BIOS implementations (and user interfaces) vary from one computer to another. The best approach here is to read the Owner's Manual of your computer to figure it out. Note that the VirtualBox will fail to start if the technology is not enabled/available on your machine.

Now you should be ready to set up the Oracle VM VirtualBox software on your machine. You need to download an installer which matches your operating system (not the virtual images which are distributing!) directly from Oracle. Please, make clear distinction between your host operating system and the guest operating system of the virtual images. You may need to explore the technology by reading articles on this subject (like Virtual Machines on Wikipedia) which are available on the Internet.

Once you're done with installing the VirtualBox itself then you will also need to install Oracle VM VirtualBox Extension Pack. This software will upgrade your installation with a number of useful extensions. After rebooting your system you should be ready to proceed to the next step of downloading and using our virtual images.  However, before you may want to read the documentation on the VirtualBox itself. There are many aspects of setting and managing VirtualBox which we wouldn't even touch in this document. We're assuming it has to be up to you to get yourself familiar with the technology. The present document covers only basic steps needed to set up and run our images. The virtualization software has many other potentially interesting settings which you may (eventually) find useful for you.

Downloading and setting up a virtual image

The virtual images can be downloaded from the following location:

We suggest using the latest analysis release. You can find a list of most recent releases in the Pre-Conda Release Notes. Note that not all of them would be packaged into the virtual images. Also note that not all platforms which we generally support at LCLS may be represented in the above mentioned collection of virtual images. For instance, we can't redistribute images based on RHEL because this is a proprietary Linux distribution. Instead of that we replace RHEL systems with the corresponding versions of the CentOS distribution.

The next step is to download an image of your choice onto a machine where you have previously installed the Oracle VirtualBox software. Virtual image files will have the .ova extension. The OVA files correspond to the Open Virtualization Format which is meant to be used by the virtualization solution manufactures to exchange virtual images. Then you will need to start the VirtualBox GUI and import the image. First try double clicking on the .ova image file you downloaded. This should bring Virtual box up and have it digest the image file. If this does not work, follow these steps:

  1. start VirtualBox
  2. locate the 'File' menu on the top left corner of the application's GUI
  3. select menu option 'Import Appliance'
  4. follow instructions suggested by the GUI on where to locate the file which you have just downloaded

It will take a few minutes for VirtualBox to "digest" the file. The software will read, unpack the input file and place the actual image (along with additional support files) some where on your file system. The actual location can be changes through one of the configuration option of the VirtualBox application. When the process is done then you should see the VM the GUI. Here is an example:

Note that the initial state of the machine will be "Powered Off".

What's inside the virtual images

Accounts, passwords

There is an important thing you need to know about the security of your machine. The machine comes with two predefined accounts:

  • root
  • pcds
Both accounts have the same default password: LCLS2014    Please, change the one as soon as you start the image and log into the system! Protecting your system is solely your own responsibility. The passwords can be changed by logging as pcds and then switching to the superuser mode using one of the following commands:


% sudo -i
% su

You should use the superuser account to manage your system (add/remove accounts, change passwords, configure the network, mount dists, etc.). The psana software has been installed using the conda system and can be used in the standard way.

There are some important notes regarding what's not available on the VM:

  • you won't be able to see your NFS home directory even if you will add your own account to the system using your sudo privilege
  • all accounts found on the machine have nothing to do with LCLS accounts
  • you won't be able to see any data directories (you can mount the ones using sshfs as explained later in this document)

Testing and using the installed machine


The virtual machine can be in either of the following states:

  • powered off (same as hibernated or temporarily suspended and saved to disk)
  • shut down (similarly to shutting down your host system; all sessions will be closed)
  • running (in memory and using CPU)
  • paused (still in memory but not using CPU)

The VirtualBox GUI has the corresponding controls to move the machine between the states. It's important to know that the machine state will be properly preserved between running and powered off states only if the machine is brought down using the GUI operations. This will allow VirtualBox to save the machine's state to disk. If you just kill the application then all modifications made to the VM system may be lost.

Enabling/disabling network connection

By default, after you start the machine, the network connection will not be enable on the VM. You shall locate the following sign on the title bar on the top right corner of the machine's GUI:

If you see what you see above then the network is disabled. You will still be able to log on that machine through the GUI, but you won't be able to ssh out of the machine. Click on that sign and then click on the name of the network interface System eth0 in order to enable the network.

Mounting host machine's directories

VirtualBox allows to make select file systems (of your choice) of your host system available within the VM. This can be configured by selecting a desired machine from the list and clicking on the Setting button on the VirtualBox top-level menu. Then proceed to the "Shared Folders" sections where you can specify which file systems of your host machine you would like to mount on the VM. You may also control what kind of access level you would allow for the directories. Note that you will need to do so when the machine is shut down (not just powered off). The directories will be mounted when the machine will start up.

Mounting data directories from PCDS

In principle, you can also mount all data directories which we have at PCDS on your virtual machine (one you start the one and logged into it as root or pcds), You will also need to enable the network as explained in the previous section. The simplest way to do so is to use sshfs. The tool is already installed on the VM. The data directories will be mounted at the usual location /reg/d/psdm/. And the mounting will require to use your real UNIX account and a password at SLAC. Here is a sample session illustrating the idea:

% whoami
% ls -al /reg/d/psdm/
total 8
drwxr-xr-x. 2 pcds pcds 4096 Apr  4 17:10 .
drwxr-xr-x. 3 root root 4096 Apr  4 17:10 ..

% sshfs /reg/d/psdm/ -o transform_symlinks -o follow_symlinks
% ls -al /reg/d/psdm/
total 80
drwxr-xr-x. 1 9997 2279 4096 Sep 26 2013 .
drwxr-xr-x. 3 root root 4096 Apr 4 17:10 ..
drwxr-sr-x. 1 9997 2279 4096 Jul 7 10:54 amo
drwxr-sr-x. 1 9997 2279 4096 Jul 7 10:54 AMO
drwxr-sr-x. 1 9997 2279 4096 Jul 15 12:18 cxi
drwxr-sr-x. 1 9997 2279 4096 Jul 15 12:18 CXI
drwxr-sr-x. 1 9997 2279 4096 Mar 4 15:08 dia
drwxr-sr-x. 1 9997 2279 4096 Mar 4 15:08 DIA
drwxr-sr-x. 1 9997 2279 4096 Jul 15 12:18 mec
drwxr-sr-x. 1 9997 2279 4096 Jul 15 12:18 MEC
drwxr-sr-x. 1 9997 2279 4096 Jun 13 14:52 mob
drwxr-sr-x. 1 9997 2279 4096 Jun 13 14:52 MOB
drwxr-sr-x. 1 9997 2279 4096 May 30 16:41 sxr
drwxr-sr-x. 1 9997 2279 4096 May 30 16:41 SXR
drwxr-sr-x. 1 9997 2279 4096 Dec 19 2013 usr
drwxr-sr-x. 1 9997 2279 4096 Dec 19 2013 USR
drwxr-sr-x. 1 9997 2279 4096 Jun 25 11:15 xcs
drwxr-sr-x. 1 9997 2279 4096 Jun 25 11:15 XCS
drwxr-sr-x. 1 9997 2279 4096 Jul 15 12:18 xpp
drwxr-sr-x. 1 9997 2279 4096 Jul 15 12:18 XPP

At this point you may run of the tutorials by:

% python /reg/g/psdm/tutorials/xcs/princeton_movie/


  • On a macbook, I could not find a "File" menu item to import the .ova image file.
    • By double clicking the .ova file image, virtual box will come up and digested it.
  • When I started the virtual machine, I got an error about not having a USB 2.0 device?
    • You did not install the Oracle Virtual Box Extension Pack.
  • When first powering on the machine, I cannot see anything.
    • There is sometimes a problem where the login screen is not using your computers video settings. After scrolling within the virtual machine so that you can see the login window, and then logging in, it should re-display within your computers video settings (after logging in).

Final notes

  • The default configuration of the virtual machine won't allow external login into the machine (one can't do 'ssh' into the system). However, it's possible to give you machine a unique IP address to allow the logins. Instructions can be found in the VirtualBox documentation. And make sure you change the default passwords of both root and pcds accounts in your virtual image.


  • No labels