GRASSLinks 3.2beta at IPPC, Oregon State University

Notes on customizing for a local installation

GRASSLinks is a World Wide Web interface to a geographic information system (GIS), offering public access to mapped information. GRASSLinks provides GIS display and analysis tools to facilitate data sharing and cooperation between environmental planning agencies, public action groups, citizens, and private entities.

GRASSLinks was created by Susan M. Huse, with the assistance of the REGIS staff, while a Ph.D. student at the University of California, Berkeley.

This version from OSU IPPC (Len Coop) will hopefully help overcome the hurdles to installation seen in previous versions.

See INSTALL file for new "quick install" instruction list. If it fails, plan to spend time studying this file and checking everything. A rule of thumb: Remember it is always file locations, owners, and permissions, or a combination that is not set right if something fails to work.


First and Foremost:

Please read the GRASSLinks copyright and disclaimer. This is similar to an opensource BSD (not GPL) license and has no restrictions other than copy of the UC Berkeley copyright and disclaimer notice. GRASSLinks has been license-compatible with open-source GRASS since January, 2002. Before that, the license was inadvertently incompatible, mainly in requiring REGIS permission for commercial use. That is no longer true.

Installation / local use of any of the GRASSLinks scripts or programs obtained from this site constitute agreement with the GRASSLinks copyright and disclaimer.


Requirements

  • GRASSLinks is a perl script and requires local access to perl. GRASSLinks has been tested under Digital Unix 4.0 and Linux Redhat 7.x. It should run on any UNIX system or any system that has Perl 4.x or 5.x installed (though it will probably need more tweaking on a non-Unix system that what is detailed herein).
  • You must have the software GRASS accessible from the same server that is running GRASSLinks and you must have some existing GRASS raster, vector and sites files. At this time, GRASSLinks is best used with the latest (currently GRASS 5.0pre5) but can be modified to work with any GRASS 4.x or 5.x release.
  • To get GRASSLinks up and running smoothly, we recommend having either the default Spearfish or Global GRASS databases (see http://grass.ibiblio.org/data.html or equivalent mirror site for obtaining these) installed to use with GRASS. A few slight modifications to files in these databases will help demonstrate certain GRASSLinks features.
  • You must have a web htdocs directory in which to locate GRASSLinks html files and helper files.
  • You must have the ability to run cgi scripts on your web server. The default cgi directory is cgi-bin, but this can be set in the configuration.
  • You will probably need access to super-user status on your system or the person with this status.
  • You will need to install the free netpbm/pbmplus ppm programs which can be downloaded off the web.
  • GRASSLinks utilizes public domain software, GRASS, created by the US Army Corps of Engineers and now developed as open source free software. We assume that anyone installing GRASSLinks already has experience using GRASS.

    Recommendations

  • Security! You or your system administrator should have the ability to understand the GRASSLinks scripts and programs so that you can decide for yourself if they are safe enough and/or practical enough to install on your system. We do not advocate taking system security lightly!
  • We ask that you email us and let us know that you are installing GRASSLinks on your system. We would like to maintain links to other GRASSLinks systems from our web site.
  • We ask that you be kind and remember that this software was written as a labour of love (no $$). We welcome very much your suggestions for improvements but, due to lack of staff and funding, will probably be slow to make changes or get back to you.
  • Please read about GRASSLinks so you understand what you are installing. Relevant links are provided at the bottom of this web page.


    Obtaining GRASSLinks Software

    You can obtain all of the scripts and programs needed to locally install GRASSLinks 3.1 by downloading this gzipped, tar file: grasslinks3.1.tar.gz

    About the GRASSLinks files and scripts

  • You should unzip and untar the GRASSLinks (hereafter referred to as GL) tar archive in an appropriate location under your server's htdocs directory so that the files therein can be accessible on the web.

  • Here is a look at the files and directories you should see:
    
    /your_system/htdocs/ (default: /home/httpd/html/)
              |
              |-glinks/ 
              |	|
    		|-about_gl.html
    		|-CHANGELOG
    		|-gl_copyright.html
    		|-gl.html
    		|-gl_matrix.html
    		|-GL_matrix.html
    		|-glreadme.html
    		|-help.html
    		|-index.html
    		|-INSTALL  
    		|-TODO     
    		|-progs/
    		|   |
    		    |-glinks.pl
    		    |-GL_forms.pl
    		    |-GL_list
    		    |-glmatrix.pl
    		    |-lookitv.sh
    		    |-do_mk_png.sh
    		    |-s.what
    		    |-lookup.c.old
    		    |-Makefile.osf.old
    		    |-Makefile.solaris.old
    		    |-clean_tmp.pl
    		    |-clean_tmp.old
    		    |-checktimes.c.old
    		|-data/
    		|-gifs/
    		|-logs/
    		|-meta/
    		|-tmp/
    		|-tnails/
    
    

    More detail on the above GL files and directories

  • CHANGELOG - Log of changes to GRASSLinks since version 3.1.1.

  • glinks/
    This is the directory in which to put GL files that need to be web accessible. This directory (and the files in it) needs to be world readable but should not be world-writeable or writeable by a group that includes the user under which your web server runs (we'll call this user web in this document).

    Files in the grasslinks directory include:

  • progs/
    Files in the progs directory are GL helper scripts / programs. These do not need to be in an htdocs directory. They should not be writeable by the world or by the web user.

    Files in the progs directory include:

  • data/
    A default location for storage of accessory HTML or txt data refereced via site and vector forms. Typically, you may have dynamic data generated by an SQL database server or some other need, but standard HTML data may be stored here. The README in this directory mentions files needed for SPEARFISH and GLOBAL datasets; you may want to delete all others.

  • gifs/
    A default location for storage of gifs and pngs used for grasslinks webpages.

  • logs/
    A default location for GRASSLinks log file, glaccess.log. You may want to change the location of this file via glconf.pl. glaccess.log is a place to monitor and debug GRASSLinks features, and will build to substantial size quickly. It may be convenient to have this in your web directory, but currently it is not set to world readable. You may rather place it where you normally put logfiles. You may want to clean this out or rotate it periodically.
  • meta/
    A default location for storage of metadata referenced from the GL_matrix.html webpage. You may want to remove all but the GLOBAL and SPEARFISH directories.

  • tmp/
    You will need to create the directory tmp inside the grasslinks htdocs directory. This directory will be used to store the temporary files created by GL. This directory should be world-readable and writeable by the web user. Since it is writeable by the web user you should be aware of the security risks this involves. This directory can grow to contain many files. You should run a cronjob such as clean_tmp.pl that automatically deletes files that are more than xx days old.

  • tnails/
    A default location for storage of gif and png thumbnail images used for GL_matrix.html raster etc files.

    Customizaton Details

  • Creating the GL_list file
    Take a look at the sample GL_list file distributed with GL. (It may be difficult to read because it has lots of characters on each line.) This file is split into five sections: 1) GRASS raster files available in GL at this site; 2) GRASS vector files available; 3) GRASS sites files available; 4) GL region definitions for use with different projects; 5) GL projects at this GL site.

    These five sections are implicitly organized by the first word (field 0) that appears in each line of the file. Each line contains a number of "fields" numbered from zero that are delimitted by the "|" character. For the GRASS files, these fields contain the following information:

    NOTE: Only fields 0-3 + 6 are used by the script glinks.pl; fields 0-5 are used by the script glmatrix.pl. Field 4 for projects is the GRASS Location

    
    EXAMPLE ENTRY in GL_list:
    raster|x|elevation.dem|Elevation DEM|Elevation DEM
    raster|x|geology|Geology|Geology
    
    vector|x|fields@PERMANENT|Fields|Fields||
    vector|x|soils@PERMANENT|Soils|||testspear|
    
    sites|x|archsites@PERMANENT|archeological sites||||
    sites|x|bugsites@PERMANENT|bug sample sites||||
    
    region|x|default@PERMANENT|Spearfish default
    
    project|x|Spearfish GRASS example dataset||spearfish|default@PERMANENT
    project|y|Global GRASS example dataset||global|default3@PERMANENT
    
    raster|r|nichols.wright@PERMANENT|Nichols and Wright Historic Shoreline and Open Water|/metadata/nichols.wright.mdata|/thumbnails/nichols.wright.gif |Source: Donald Nichols and Nancy Wright, USGS, 1971, Scale 1125,000 Basic Data Contribution.
    
    

    The project aspect of GL is important to understand . GL was developed at REGIS where we make available many GRASS files. We organize these files according to the projects for which they were created. In GL, the project notion allows us to present different views / subsets of all of our GRASS files to users, and to allow multiple GRASS Locations. It is a way of organizing the files as the user may wish to view them. We also have one super-project that includes all of our site's GRASS files. GL will work fine if you just have one project. But you need to configure GL as though you might have more than one.

    The project section of the GL_list file contains information about each GL project:

    NOTE: See the demo GL_list file for more examples of how to structure the project information.

  • Creating the GL_matrix.html file
    You should create the GL_matrix.html file after you create the GL_list file. See above for more info on this file.

  • Customizing the gl.html file:
    You should customize this file after creating the GL_list file. What is important to note in this page is the method by which the GL cgi script is called. For example:

    <a href="/cgi-bin/glinks.pl?PROJECT=x+ANALYSIS=display1">

    The script when launched with the GET calling method requires that a PROJECT code as specified in the GLlist file be passed as an argument. The ANALYSIS argument is also required. The display1 value launches the main GL display routine from which all other GL routines are available.

  • Customizing the GRASS environment
    Before you can run GRASSLinks you need to set up some GRASSLink's tailored GRASS mapsets. You need to decide how many simultaneous GRASSLinks users you will allow on your site. We allow a default total of 3. For each one, you need to create a GRASS mapset, for example: grasslinks1.. grasslinks3. You will also need a grasslinks0 mapset for GL's private use. Note that this naming scheme for the mapsets is important to maintain.

    In addition to the standard GRASS mapset files and directories, you will need to add two files to each mapset: 1) a .grassrc5 file and 2) an empty file named UNLOCK. The UNLOCK file is renamed LOCK when GL uses the mapset and is renamed UNLOCK when GL is finished. The .grassrc5 file is used to set up the GRASS environment needed to run GRASS commands. Each of the GRASS mapsets (and all files and subdirectories under it) will need to be readable and writeable by the web user. (But they should not be world-writeable). You should understand the system security risks that this poses.

    Here is a sample of a GRASS mapset structure needed by GL if two simultaneous GL users are allowed:

    
    	/usr/local/data/global/
    		|
    		|- grasslinks0/
    			|
    			|- .grassrc5
    
    		|- grasslinks1/
    			|
    			|- .grassrc5
    			|-UNLOCK
    		|
    		|- grasslinks2
    		|	|
    			|- .grassrc5
    			|-UNLOCK
                    |
                    etc.
    

    Here is a sample of a GRASS .grassrc5 file needed by GL:

    GISDBASE: /usr/local/data
    LOCATION_NAME: global
    LOCATION: /usr/local/data/global/grasslinks1
    PAINTER: ppm
    GRASS_GUI: text
    MAPLP: pmap.grasslinks1
    MAPSET: grasslinks1
    
    NOTES:


  • Customizing the glinks.pl/glconf.pl cgi perl script

    This should represent the biggest challenge in the GL installation. However, if you have reviewed the information above and created all the necessary GRASS mapsets, files, and the GL_list file, then this should be just tedious but not too confusing.

    1. Print out and read the cgi perl script glinks.pl
      Since GL will be running on your system via this script, it is best to read it through and understand what it is doing and what potential security risks it might present for your system.

    2. Configure the necessary subroutines for your environment
      The following is a list of GL subroutines that you should edit to indicate appropriate options, files, directories, programs, etc., on your local system. There are many comment lines in the script itself to help you. As you work through this configuration your knowledge of how GL works will improve. Other subroutines could also be editted, but these are the most critical ones:

      • set_glvars - this subroutine sents GL variables (in glconf.pl).

      • set_GRASSvars - this subroutine sets GRASS specific GL variables (in glconf.pl).

      • set_gloptions - this subroutine sets some minor GL options and defaults and can be used "as is" but you should review.

      • lock_Gmapset - this subroutine sets some GRASS variables depending on which GL GRASS mapset the user will be using. It assumes the presence of mapsets with the name structure grasslinks1, grasslinks2, etc. You probably don't need to make any changes but you should review.

      • begin_html - this subroutine creates the HTML headers for each HTML document dynamically created by GL. You can use as is but will probably want to tailor it for your local site.

      • end_html - this subroutine creates the HTML footers for each HTML document dynamically created by GL. You can use as is but will probably want to tailor it for your local site.

    3. GRASSLinks access log
      GL can maintain a log of all accesses if you set the $GL_ACCESS_LOG variable in the set_glvars subroutine (in glconf.pl). This might be helpful to track any security problems. You should not let this file be publically accessible. Also not that it could grow out of control if your GL site has a lot of visitors.

    4. You must edit the first line of the glinks.pl script to indicate the location of perl on your system! (default is #!/usr/bin/perl)

    5. You must make glinks.pl a recognized cgi script on your system.
      For example, placing the script in a cgi-bin directory.


    FINAL NOTES:

  • You can make other customizations to GL as you see fit, but you cannot violate the spirit of the Copyright.

  • You are basically on your own in terms of help with the installation. We very much lack staff time to assist you but will try to respond to your email as time permits.

  • We would appreciate hearing any feedback or suggestions you have about GL. In particular, if you review the glinks.pl cgi script and see ways to make it safer or more efficient please let us know. We will post at this location any future updates to the script that incorporate your suggested changes.


  • Send us Email!
  • GRASSLinks at OSU IPPC
  • Oregon State University"


    GRASSLinks Copyright Notice and Disclaimer

    
    Copyright (c) 1994-98
    Susan M. Huse and The Regents of the University of California
    All rights reserved.
    

    Copyright (c) 2002 Oregon State University All rights reserved.


    Last updated 09/21/2002