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:
- gl.html -
This is the SPEARFISH and GLOBAL example main html page that launches GL.
It should be renamed index.html. Currently, index.html represents all
IPPC GRASSLinks datasets so may be replaced by this file.
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.
- 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 glmatrix.pl (see below).
The GLOBAL and SPEARFISH only version of this file is gl_matrix.html.
- glreadme.html -
This file. No need to make changes.
- 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.
- INSTALL -
A quick install guide intended to get you up and running with the SPEARFISH or GLOBAL
datasets without excessive grief or pain. Mileage may vary.
- TODO
A file to track ideas and plans for improvement to GRASSLinks.
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:
- glinks.pl - the main GL perl cgi-script. This will need to be moved to
a cgi directory. GL won't run without this script. Because user settings were
moved to glconf.pl, you may not need to make changes to this file.
- glconf.pl - user configuration settings for glinks.pl.
This will need to be moved to a cgi directory. The two subroutines in this file
were removed from glinks.pl to assist in locating major settings. This
will definately need configuration to run on your local system.
- 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 glinks.pl cgi-script. To start with a copy
that only includes the GRASS example datasets GLOBAL and SPEARFISH, copy GL_list.default
to GL_list.
- GL_forms.pl - this is a subroutine that can be customized to add HTML to
query results to allow HTML FORMS to do all sorts of web-based look ups, such as SQL
database queries, run models, display metadata, link to related web sites, anything
you want. Generally, here is where you store the static part of an HTML FORM, then
the cats file or site_lists file will contain the dynamic part, and GRASSLinks queries combines
the two
- glmatrix.pl - see GL_matrix.html above. This accessory script has a few
settings you may want to explore, such as to limit inclusion of only one or two
GRASSLinks projects in the resulting GL_matrix.html file.
- lookup.c.old and related makefiles Makefile.osf.old, Makefile.solaris.old. -
NOTE: these programs have not been used or updated for GRASSLinks 3.2beta and may be
difficult to use on Linux systems. It remains a TODO task to update and generalize
these programs (if this feature is to be retained; currently not supported).
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.
- lookitv.sh - a shell script used to call v.what for querying GRASS vector
files. If VECTOR QUERIES do not appear, GRASSLinks cannot find or run this script. Place it someplace your webuser can run it. Apache probably will not allow this script to remain here. Specify its location in glconf.pl.
This script is currently a single line, but may need to be altered
for versions of GRASS other than 5.0pre5 due to recent changes to v.what.
- do_mk_png.sh - a shell script used to make thumbnails of all rasters in a CELL directory. Copy this to any GRASS user directories to run during a GRASS session to make a quick batch of PNG thumbnails, which are helpful for using with the GL_matrix.html listing of GRASSLinks data layers. After running, you would mv *.png to default directory /home/httpd/html/glinks/tnails. Note that this is crude and will not perfectly match the files you specify in GL_list, but it can save you time. Modify / use at your own risk.
- s.what - (old) a borne shell script used for querying GRASS sites
files. s.what is now part of GRASS 5.x, so this version probably can be ignored/deleted. For older versions of GRASS, this script may need to be placed in your GRASS scripts directory.
- clean_tmp.pl - a simple perl script (for a cron job) used for cleaning up
temporary GL files that are more than xx days old. This is offered as alternative to
the GRASSLinks 3.1 scripts below of how to manage the temporary files created by GL. Customize for
your own system and Use at your own risk!
- clean_tmp.old and checktimes.c.old -
NOTE: these are GRASSLinks 3.1 programs not implemented but rather replaced by clean_up.pl above. You
may decide this solution suits your needs so it remains available here.
This is 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.
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:
- 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 (GRASS LOCATION if project)
- field 5 - htdocs path and filename for relavent thumbnail gif
- field 6 - Optional name of vector and site form variables for custom query lookups (see GL_forms.pl for example setup for use of these variables)
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:
- 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 Location setting for this 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.
- 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.
- 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.
- 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.
- 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)
- 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"
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