GRASSLinks 3.1 at REGIS, UC BERKELEY
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.
First and Foremost:
You must read and agree to the
GRASSLinks copyright and disclaimer.
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. 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.
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.
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.
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/
|
|-grasslinks/
| |
|-GL_matrix.html
|-about_gl.html
|-gl_copyright.html
|-gl.html
|-glreadme.html
|-glreadme.txt
|-help.html
|-green_line.gif
|
|-progs/
| |
|-gl31.pl
|-GL_list
|-glmatrix.pl
|-lookup.c
|-Makefile.osf
|-Makefile.solaris
|-s.what
|-clean_tmp
|-checktimes.c
More detail on the above GL files and directories
grasslinks/
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:
- gl.html -
This is the main html page that launches GL. It could be renamed index.html.
This file is distributed as a template/model for your own GL installation.
You will need to edit it to tailor it to your own site.
We ask that you keep on this main GL page a link to the GL Copyright,
REGIS, and "more info about GL". These links are already provided at
the bottom of the gl.html template.
You can leave them there or make an indirect link via another html page.
- help.html -
This is the GL help document. It doesn't need to be changed, but check it over
in case it has some relative url links that won't work on your system.
- GL_matrix.html -
This is an html table view of the GRASS files available on your site
that is provided as a service to your
GL users. It is an optional file that you decide
whether or not to provide. It is created by a helper perl script in the
grasslinks/progs directory called glmatrix.pl.
The copy of the file provided with the GL distribution is just for reference.
- green_line.gif -
This is a decorative line gif that is used to jazz up the GL web pages.
No need to change.
- glreadme.html (and glreadme.txt) -
This file as well as a text version of it. No need to make changes.
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:
- gl31.pl - the GL perl cgi-script. This will need to be moved to
a cgi directory. GL won't run without this script and gl31.pl will need to
be heavily customized! More details below.
- GL_list -
This is the file that should contain a list of GRASS files
(raster, vector, sites) that will be available at your site via GRASSLinks.
The one included in this distribution is just an example of how the file
should be structured. This is the main helper file for the GL cgi-script.
GL won't run without it. It doesn't need to be in the htdocs directory and it
should probably be located with the gl31.pl cgi-script.
- glmatrix.pl - see GL_matrix.html above.
- lookup.c and related makefiles Makefile.osf, Makefile.solaris. -
The lookup.c is used by the GL script subroutines that create little gifs for
map legend boxes. The two makefiles are provided as an example of how to compile
lookup.c on your system. In order to compile you will need to have GRASS source
files on your system. Read the makefiles and go to the GRASS website for more
info. None of the GL legends will display properly without lookup.c installed.
- s.what - a borne shell script used for querying GRASS sites
files. This script should be placed in your GRASS scripts directory.
- clean_tmp and checktimes.c - a borne shell script and its
helper C program used for cleaning up temporary GL files that are more than
an hour old. These are offered as an examples only of how to manage
the temporary files created by GL. Use at your own risk!
- netpbm/pbmplus ppm software -
These freeware programs are not provided in
the GL distribution. You will need to do a search and download off the web.
They should be kept in the progs directory and/or with the other GL helper
programs. You can review the GL cgi-script in detail to see which specific
programs are required by GL. GL will not work without this software.
tmp/
You will need to create the directory tmp inside the grasslinks htdocs
direcotory. 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 that
automatically deletes files that are more than 1 hour old.
legendGifs/
You will need to create the directory legendGifs inside the grasslinks htdocs
direcotory. This directory will be used to store the tiny gif files created by
the GL legend subroutines. THese files should not be deleted. They will be created once
as users make GL legends and then re-used again and again. This will make GL process
much faster. 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.
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
four sections: 1) GRASS raster files available in GL at this site; 2) GRASS vector
files available; 3) GRASS sites files available; 4) GL projects at this GL site.
These four 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:
- field 0 - the GRASS file type (raster, vector, or sites)
- field 1 - the code(s) for the project(s) to which this file applies,
or "!" if it applies to all projects or empty if you
want to "comment out" the file.
- field 2 - the actual grass file name in the form grass_filename@mapset
- field 3 - a title / brief description for the grass file
- field 4 - htdocs path and filename for relavent metadata file
- field 5 - htdocs path and filename for relavent thumbnail gif
- field 6 - Longer, more detailed description of the file
NOTE: Only fields 0-3 are used by the script gl31.pl; all fields
are used by the script glmatrix.pl.
EXAMPLE LINE:
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. 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:
- field 0 - the word "project" to denote project information line
- field 1 - the code for this project. Must be a single unique alpha
or numeric character.
- field 2 - a title for the project that appears on top of GL html pages
- field 3 - a gif thumbnail image to represent this project
- field 4 - the default GRASS region setting for this project
NOTE:
See the demo GL_list file for 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/gl31.pl?PROJECT=r+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 total of 5. For each one, you need to create
a GRASS mapset, for example: grasslinks1.. grasslinks5.
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 .grassrc 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 .grassrc 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:
/grass/data/sfbay/
|
|- grasslinks0/
|
|- .grassrc
|- grasslinks1/
|
|- .grassrc
|-UNLOCK
|
|- grasslinks2
| |
|- .grassrc
|-UNLOCK
Here is a sample of a GRASS .grassrc file needed by GL:
GISDBASE: /grass/data
LOCATION_NAME: sfbay
LOCATION: /grass/data/sfbay/grasslinks1
PAINTER: ppm
MAPLP: /htdocs/grasslinks/tmp/pmap.grasslinks1
MAPSET: grasslinks1
NOTES:
Customizing the gl31.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.
- Print out and read the cgi perl script gl31.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.
- 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.
- set_GRASSvars - this subroutine sets GRASS specific GL variables.
- 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.
- GRASSLinks access log
GL can maintain a log of all accesses if you set the
$GL_ACCESS_LOG variable in the set_glvars subroutine. 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.
- You must edit the first line of the gl31.pl script to indicate
the location of perl on your system!
- You must make gl31.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 gl31.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 REGIS, UC Berkeley
REGIS, UC Berkeley
Copyright (c) 1994-98
Susan M. Huse and The Regents of the University of California
All rights reserved.
Permission to use, copy, modify, and distribute this software and
its documentation for educational, research and non-profit purposes,
without fee, and without a written agreement is hereby granted,
provided that the above copyright notice, this paragraph and the
following three paragraphs appear in all copies.
Permission to incorporate this software into commercial products may
be obtained by contacting the University of California.
This software program and documentation are copyrighted by Susan
M. Huse and The Regents of the University of California.
The software program and documentation are supplied "as is",
without any accompanying services from Susan M. Huse or The Regents.
Susan M. Huse and The Regents do not warrant that the operation of the
program will be uninterrupted or error-free. The end-user understands
that the program was developed for research purposes and is advised not
to rely exclusively on the program for any reason.
IN NO EVENT SHALL SUSAN M. HUSE OR THE UNIVERSITY OF CALIFORNIA
BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL,
OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS, ARISING OUT OF
THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF SUSAN M.
HUSE and/ or THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF
THE POSSIBILITY OF SUCH DAMAGE. SUSAN M. HUSE AND THE UNIVERSITY OF
CALIFORNIA SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN
"AS IS" BASIS, AND SUSAN M. HUSE AND THE UNIVERSITY OF CALIFORNIA
HAVE NO OBLIGATIONS TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,
ENHANCEMENTS, OR MODIFICATIONS.
Last updated 06/02/98