LAS Installation and Configuration

Installing LAS

• Requirements

• Installation

• Adding datasets

• Debugging

Understanding/modifying the XML configuration file

Installing LAS

We have endeavored to make installation of the Live Access Server (LAS) as easy as possible. However, some preparation of your site will be required before you can begin using the LAS. Once you have made sure that your site has all of the required software, the actual installation of the LAS software should be very straight forward.

Note: you will need super user privilege during the setup procedure.

Requirements

Much of the functionality of LAS comes from harnessing other, proven software components. The LAS server, as opposed to the client side interface, uses a number of Perl modules that must be installed on your system. Please check that your system has all necessary components before attempting to install LAS.

You must have the following software:

• Perl (at least 5.005)

• The following Perl modules:

  • URI::URL

  • XML::Parser

  • HTML::Parser

  • MD5

  • Date::Calc

  • Time::JulianDay

  • Date::Manip

  • LWP::UserAgent

  • CGI

The easiest way to get these modules is by using the Perl CPAN module. The CPAN module will automatically download, build, and install Perl modules for you. Type perldoc CPAN for more info.

• NetCDF library

• the NetCDF Perl module

These NetCDF components are recommended rather than required and will allow you to automatically generate XML configuration files from COARDS compliant NetCDF files. We strongly encourage the use of netCDF data files wherever possible.

Note: LAS has only been tested with the netCDF 2.4.x library and Perl module.

• A HTTP server.

Note: LAS has only been tested with Apache, v1.3.x. LAS will not work with earlier versions of Apache.

• Ferret (at least 5.000).

Installation

1. Pick a directory where you want the LAS files to go (referred to in this document as $lasroot), cd to that directory and untar the files:
   
   gunzip -c las3.tar.gz | tar xvf -

2. The LAS configure script should be run as root, since it has to change file ownership. You can still run it as a non privileged user, but you will have to change file and directory ownership and protection by hand.

3. If your Ferret environment is not set up, you should source the Ferret startup script. If Ferret is installed in /usr/local/ferret, then type:
   
   source /usr/local/ferret/ferret_paths

4. Change to the lasxml directory and run the configure script:
   
   cd lasxml
   ./configure
   
   The configure script will ask you a number of questions, and make some tests to make sure you have all of the required software. Unless you plan on supporting multiple LAS servers on one Web server, the default answers should suffice.

5. After the script has completed, you need to change your Web server configuration file. If you are running Apache, the script will tell you which commands have to be added to the server config file. If not, the script will give you more general configuration instructions. Add the new commands to the server configuration file, restart the server, and you should be ready to test the sample LAS configuration.
   If you used the default configuration, and your Web server is on foo.com, just point your browser to:

   http://foo.com/las/

   to run LAS.

Adding datasets

Almost all of the configuration information used by LAS is stored in a XML file in $lasroot/lasxml/server/las.xml.

If your data is in COARDS compliant netCDF format, you can automatically add datasets to this configuration file. If you want to do this for a netCDF file named /a/foo.cdf, you can:

• cd to $lasroot/lasxml/xml/perl

• Type:

  perl addXml.pl ../../server/las.xml ../../server/las.xml /a/foo.cdf

• cd to $lasroot/lasxml/server

• Type:

  make

The first command adds the metadata from /a/foo.cdf to the XML configuration file; the second automatically generates JavaScript and HTML for the server.

If you now reload the LAS page (using Shift-Reload), the new dataset will appear in the left hand frame.

Note: you should always use Shift-Reload to reload the LAS home page after regenerating JavaScript and HTML. JavaScript errors that occur when accessing LAS are almost always due to automatically generated JavaScript being out of synch with LAS HTML. Shift-Reload forces your browser to clear its cache and use the latest version of JavaScript and HTML supplied by the Web server.

Debugging LAS

If you've diligently followed the installation instructions and LAS doesn't work, here's what you can do:

• If you make any changes to the configuration file in $lasroot/lasxml/server/las.xml, you should either rerun the configure script, or cd to $lasroot/lasxml/server and type make.

• Make sure the JavaScript and HTML are in sync in the browser by using Shift-Reload to reload the LAS home page. You must do this after making changes to the LAS configuration file. If you get any JavaScript errors, give this a try.

• Check your server error log file for error messages from LAS. If you are using Apache, the error log file is usually in <apacheRoot/logs/error_log or <apacheRoot>/var/logs/error_log.

• Check the LAS server logs in $lasroot/lasxml/server/log/access and $lasroot/lasxml/server/log/errors.

• Check debugging information on the last LAS access is in $lasroot/lasxml/server/log/GenericLAS_debug.txt

• If you still can't figure out the problem, send mail to: las@pmel.noaa.gov

Understanding/modifying the XML configuration file

Unfortunately, metadata in netCDF files is frequently missing or inadequate. As long as you are using only COARDS compliant netCDF files, you can still use the automatic XML generation technique described above to generate a template configuration file, which you can then edit. If you are using other types of datasets, you have to manually insert the metadata for the dataset.

You will have to modify the XML configuration file if your metadata is missing or insufficient; to do this, you will have to understand the syntax and semantics of the LAS XML configuration file. A sample XML file is below, followed by definitions for LAS XML elements and attributes.

Sample XML file

<?xml version='1.0' ?>
<lasdata>
  <institution name="Pacific Marine Environmental Lab"
   url="http://www.pmel.noaa.gov"/>
<!-- Define operations -->
    <operations url="http://foo.com/las-bin/LASserver.pl" >
      <shade name="Shade a variable" class="LAS::Server::Ferret" method="draw">
        <arg type="variable"/>
         <arg type="region"/>
       </shade>
    </operations>
<!-- Define datasets/variables -->
   <datasets>
    <coads_climatology_cdf name="COADS Climatology" url="file:coads_climatology" doc="doc/coads_climatology.html">
     <variables>
      <airt name="Air Temperature" units="DEG C">
       <link match="/lasdata/grids/coads_climatology_cdf_grid"/>
      </airt>
      <sst name="Sea Surface Temperature" units="Deg C">
       <link match="/lasdata/grids/coads_climatology_cdf_grid"/>
      </sst>
     </variables>
     <composite>
      <wind_vectors name="Wind vectors" js="VecVariable">
       <link match="../../variables/uwnd"/>
       <link match="../../variables/vwnd"/>
      </wind_vectors>
     </composite>
    </coads_climatology_cdf>
   </datasets>
<!-- Define grids -->
   <grids>
    <coads_climatology_cdf_grid>
     <link match="/lasdata/axes/coads_climatology_cdf_COADSX"/>
     <link match="/lasdata/axes/coads_climatology_cdf_COADSY"/>
     <link match="/lasdata/axes/coads_climatology_cdf_TIME"/>
    </coads_climatology_cdf_grid>
   </grids>
<!-- Define axes -->
   <axes>
    <coads_climatology_cdf_COADSX type="x" units="degrees_east">
     <arange start="21" step="2" size="180"/>
    </coads_climatology_cdf_COADSX>
    <coads_climatology_cdf_COADSY type="y" units="degrees_north">
     <arange start="-89" step="2" size="90"/>
    </coads_climatology_cdf_COADSY>
    <coads_climatology_cdf_TIME type="t" units="month">
     <arange start="1-1-16" step="1" size="12"/>
    </coads_climatology_cdf_TIME>
   </axes>
  </lasdata>

XML Element and Attribute Definitions

The elements and attributes that make up a LAS XML specification are defined below. Note the following:

• When <*> is used for a element tag, it implies that the tag can be any string compliant with the XML specification, as long as the tag is unique.

• Regular expressions are used for describing the children of an element. For example, dataset* implies that 0 or more child dataset elements are required; dataset+ implies that 1 or more child dataset elements are required.

Lasdata element

The lasdata element is the root of the LAS XML hierarchy.

Link element

The link element is used to associate one part of the XML specification with another. It is analogous to the anchor tag in HTML, with the exception that the contents that are linked to are substituted in place. The following XML:

<a>
  <b>
    <link match="/a/d"/>
  </b>
  <d name="foo"/>
</a>

is equivalent to:

<a>
  <b>
    <d name="foo"/>
  </b>
  <d name="foo/>
</a>

Datasets element

The datasets section contains information on all of the datasets supported by the server. Here you will find metadata such as variable names, variable units, or the file or URL to be associated with a variable or dataset.

Dataset element

Each dataset is described by a dataset element. The name of the element can be anything but properties or institution; the name must be unique. It is coads_climatology_cdf in the sample file.

Variables element

Composite element

Composite elements are used to describe "virtual" variables that are composed of one or more dataset variables.

Comp_tag element

Variable element

Grids element

Grid element

Axes element

Axis element

Arange element

V element

Properties element

Properties are general purpose tags that can be associated with a LAS XML element. LAS currently uses properties to associate visualization "hints" for Ferret with datasets or variables. A set of Ferret properties might look like:

<properties>
  <ferret>
    <size>0.25</size>
    <format>netCDF</format>
  </ferret>
</properties>

The child elements of the <properties> tag can be anything; it is up to the server application to decode their semantics.

Institution element

Operations

Operation

An operation is used to map a browser user interface action to a Perl subroutine or method on a LAS server. For instance, there is one operation defined in the sample XML file above; this operation maps the UI action shade to the subroutine draw in the Perl package LAS::Server::Ferret.

Arg

Extending LAS

Virtual Variables

Custom Plots

TODO

Adding Other Visualization Tools

TODO

Comments to: las@pmel.noaa.gov
3/16/00