AER_VM - NOAA/ESRL aerosol data editing suite in a virtual machine environment

INTRODUCTION

	AER_VM is a software system that lets members of the NOAA/ESRL collaborative aerosol monitoring network run software for viewing and editing their data on their local computer.  It uses virtual machine technology, preinstalled with the NOAA/ESRL software for synchronizing station data with the NOAA/ESRL repository, displaying the data, and making corrective edits.  The "client" software runs in a Linux environment (CentOS) in the virtual machine, while the "host" system can be running a wide range of operating systems (Microsoft Windows, Macintosh OS X, Linux, and others).

PREREQUISITES

	AER_VM is based on VMware virtual machine software.  The first step in using the AER_VM software is to download VMware's free Player software for your computer's operating system, available at http://www.vmware.com/download/desktop_virtualization.html.  Full instructions for installing the player software are provided on the VMware web site.

	VMware does not provide free player software for Mac OS, you will need to purchase VMware Fusion, also available at http://www.vmware.com/download/desktop_virtualization.html, to use the AER_VM software on Mac OS X.  If you don't want to buy Fusion, 'virtualbox' (http://www.virtualbox.org/) will purportedly run AER_VM, however we do not support this and cannot give you assistance on getting this set up.

INSTALLATION

	To install AER_VM, you need to unpack the compressed file containing the AER_VM software.  This can be downloaded from ftp://ftp.cmdl.noaa.gov/aerosol/etc/vm/AER_VM.tar.bz2, or copied to your local hard disk from the DVD or flash drive provided by NOAA/ESRL.  If you are using Mac OS X or Linux, just copy the file to the folder on your hard disk where you want to install the AER_VM files, double click on it, and follow your computer's instructions for extracting the AER_VM folder.

	If you're running Windows, you will need software that can extract 'tar.bz2' compressed archive files.  Try double-clicking on the AER_VM.tar.bz2 file to see if your computer already has the required extraction software installed.  If you need a .tar.bz2 extractor, we have tested ICEOWS and 7-Zip (available at http://www.iceows.com/HomePageUS.html and http://www.7-zip.org/ respectivly) under Windows XP with the AER_VM.tar.bz2 file.  After you have downloaded and installed the extractor software, you should be able to double-click on the AER_VM.tar.bz2 file to extract the AER_VM folder from the .tar.bz2 achieve. (the AER_VM folder might contain version nameing at the end, eg. "AER_VM - 10.05 (20100503-01)", whenever the AER_VM folder or AER_VM.vmx is referenced, it applies to the full name with versioning.)

USAGE

	To run the AER_VM software, just double-click on the AER_VM.vmx file in the AER_VM folder that you just extracted.  Alternatively, you can open the VMware Player software, click File.. Open from the menu bar, browse to the AER_VM folder on your hard disk, and select the AER_VM virtual machine.  Log in with the user name and password supplied by NOAA/ESRL; if you don't have this contact John.A.Ogren@noaa.gov to request it.

	The toolbar at the top of the AER_VM client window contains drop-down menus for  "Application", "Places", and "System" that are part of the CentOS Linux distribution.  Refer to any of the multitude of Linux "how-to" books for information on how to use Linux.  The other icons on the tool bar provide access to the programs for working with your data, including
	- File Browser: to navigate the file system
	- Terminal: to open a command-line window for typing in Linux commands
	- cpx2: to run the NOAA/ESRL aerosol data visualization and editing software
	- make_tunnel: to enable remote access to the virtual machine from NOAA/ESRL, for troubleshooting and maintenance
	- sync data: to synchronize the data and programs on the virtual machine with the data repository at NOAA/ESRL
	- Shutdown: used to power off the machine safely when finished using.

	After you have logged in, you need to configure your setup for your station.  To do this, click on the icon in the upper right corner that looks like a hand pointing at a multi-colored square.  This is the station switcher, and the location you will go if you have multiple stations to switch between.  Once the menu pops up, click "new" and enter your stations three letter identifier, then click "OK".  Now click again on the icon in the upper right corner, now you will see your station listed in the menu, click on it to set it to your current station.
	This step only has to be done once if you only have one station, if you have more than one station perform the steps above again to add each additional station.

	Once you have setup your stations (above) you must register your copy of AER_VM to obtain the required authentication credentials to connect to servers at NOAA/ESRL where your raw data is stored.  To do this, open a terminal and run "bash /aer/prg/vm/firstBoot.sh", follow the onscreen prompts to register your copy AER_VM.  Once you have registered, someone at NOAA with review your registration request and approve your access.  Once your access is approved you will have access to all of your stations data.

	To sync your data, now run the rsync_mystn script by clicking on its icon on the right of the top toolbar (with the planet picture).  This will synchronize your data with the repository at NOAA/ESRL, and make sure that your system has the latest versions of the NOAA/ESRL data visualization and editing software.  The first time you run this, please run it twice in a row, regularly you should run this script at the start and end of each editing session.

	Now you can run the NOAA/ESRL data visualization and editing software by clicking on the 'cpx2' red apple icon (on the middle right of the toolbar), if you want to use the old software, click on the xshow_mystn icon (On the center side of the icons on the left of the toolbar).

	If while you're running in VMware, you want to access your host system, you need to press <Ctrl> and <Alt> at the same time to release your mouse from the VM, now to "capture" your mouse again, just click in the VM and you're back to controlling the VM's mouse.  On Mac OS X, press the <Ctrl> and <Command> (open apple symbol) keys.

	Once you are done using AER_VM, you should shut it down cleanly: click on the Shutdown icon on the far right of the top toolbar, which will open the shutdown menu, click "Shutdown" one last time, and wait until the screen goes completely black, and/or disappears before closing Vmware, you may have to press the escape keys (see previous paragraph) to gain control of your mouse after shutdown is complete.

	NOTE: Transferring files to/from the virtual machine.
	If you want to move or grab files from another computer on your network, we think using the File Browser (mentioned above) is the easiest way.  First you need to open the File Browser, then click on the "Computer" button along the top, now double click on Network.  Some of your computers will be listed here, if you see one you want to connect to, type in on the address bar sftp://USERNAME@COMPUTERNAME/ replacing the USERNAME and COMPUTERNAME appropriately.  If the computer isn't there then you need to browse (double click on ) the "Windows Network" listing, continue to look through here for the computer you want to access, if you can't find the computer, you may need to enable "File Sharing" on the computer you want to connect to, talk to your System Administrator for assistance with this.

	If you want to transfer files from your virtual machine to the host machine (if the host machine is running Windows), first download WinSCP (available free at http://winscp.net/eng/download.php).  Next you need to find the IP address of the virtual machine, when at the desktop open up a Terminal windows, and type in '/sbin/ifconfig' and press enter, look for a section labeled eth0, and a line titled "inet addr:" take the following group of numbers (should be something like 192.168.100.5).  Now on the host machine open winSCP, and type in those numbers in the hostname field, and the username and password you use to log-in in the username and password fields, then click connect.  Now you can drag files to and from the VM to the host machine!

	NOTE: Setup for Directly sending data to the VM
	The note is intended for anyone wishing to send all data collected in their LiveCPD installation directly to their AER_VM installation, bypassing NOAA computers completely. By following the procedures in this document, no data will be sent to NOAA.  This approach is provided for stations that wish to retain complete control over their raw data, but also for situations where there is no or limited internet access and immediate processing and viewing of the data is required (e.g., field campaigns in remote locations).

	This note assumes that you have both a working LiveCPD installation and a working AER_VM installation.  If you haven’t already sent your IP to John.A.Ogren@noaa.gov for access to software updates, hold off for now.  We will be changing your IP so you will need to send a new one anyway.

	This method relies on having ssh network access (TCP port 22) to the AER_VM system from the LiveCPD system.  Step2 is different if AER_VM does not have a publically addressable IP address. If this is the case, please contact your system administrator for the appropriate values.

	Step1: Setting AER_VM for bridge networking
	As we will now be making direct connections to the VM from LiveCPD, our current method of networking will no longer work so we must change it to bridged networking.  If you have problems getting bridged networking to work you will need to contact your system administrator, as the settings on AER_VM are heavily reliant on your network is setup.

	1. Power on AER_VM
	2. While AER_VM is booting, look on the right side of the lower edge of the window for the two icons: 1.<two linked computers> and 2.<two linked computers but grayed out> .  Remember where these are, and which one is which, because we will be changing them.
	3. Click on icon 1 to open a menu, and then click settings.
	4. In the box that opened click on both connected and connect at power on.
	5. Click OK, now click on the other icon and click settings.  Now click to uncheck both connected and connect at power on.
	6. Now reboot AER_VM to make our changes take effect.

	Now that you have bridge networking setup, follow the directions in the README supplied with AER_VM to send your IP if you want to get software updates. (If you do not have AER_VM 10.06 or greater, then you will need to run the update script at least twice.)

	Step2: Setting up LiveCPD
	Now we will be implementing the setup on LiveCPD to configure everything else needed both on LiveCPD and on AER_VM.

	1.Log in to AER_VM, once you’ve logged in click on <terminal> in the upper bar, and type getip<Enter>.  You should receive a number back that reads something like 123.123.123.123, this set of numbers will be referred to below as <vm.ip>.
	2.Open a terminal on the LiveCPD system and run:
	scp cpd@<vm.ip>:/aer/prg/bash/vm/dataToVM.sh ./
	3.Enter your cpd password.
	4.Once it’s finished, run “bash dataToVM.sh”
	5.Enter <vm.ip> where asked.
	6.You will be requested for your AER_VM password twice; once this is finished running your data will now be sent to AER_VM.


If you have questions or comments on the AER_VM package or documentation, please contact John Ogren at NOAA/ESRL (John.A.Ogren@noaa.gov; +13034976210).
(Document written by David Stearns <David.Stearns@noaa.gov>, last updated 26 May 2010.)