.ig >>
<STYLE TYPE="text/css">
<!--
        A:link{text-decoration:none}
        A:visited{text-decoration:none}
        A:active{text-decoration:none}
-->
</STYLE>
<title>ploticus: direct cgi mode</title>
<body bgcolor=D0D0EE vlink=0000FF>
<br>
<br>
<center>
<table cellpadding=2 bgcolor=FFFFFF width=550 ><tr>
<td>
  <table cellpadding=2 width=550><tr>
  <td><br><h2>Direct CGI mode</h2></td>
  <td align=right>
  <small>
  <a href="../doc/Welcome.html"><img src="../doc/ploticus.gif" border=0></a><br>
  <a href="../doc/Welcome.html">Welcome</a> &nbsp; &nbsp;
  <a href="../gallery/index.html">Gallery</a> &nbsp; &nbsp;
  <a href="../doc/Contents.html">Handbook</a> 
  <td></tr></table>
</td></tr>
<td>
<br>
<br>
.>>

.TH Direct_CGI_mode PL "18-APR-2002   PL ploticus.sourceforge.net"


.SH Direct CGI mode
.ig >>
<a href="pl.1.html">
.>>
\0pl
.ig >>
</a>
.>>
may be invoked directly from URLs in HTML pages, to create plots 
.ig >>
<a href="dynamic.html">
.>>
\0on the fly.
.ig >>
</a>
.>>
Direct CGI mode can produce pseudo-GIF, PNG, JPEG, 
.ig >>
<a href="svg.html">
.>>
\0SVG or SVGZ.
.ig >>
</a>
.>>
Caution: there are 
.ig >>
<a href="#security">
.>>
\0CGI security concerns
.ig >>
</a>
.>>
that must be fully understood by 
the programmer before using pl in direct CGI mode.
Other strategies for
.ig >>
<a href="dynamic.html">
.>>
\0on the fly graphing
.ig >>
</a>
.>>
are discussed
.ig >>
<a href="dynamic.html">
.>>
\0here.
.ig >>
</a>
.>>
.LP
To use ploticus in direct CGI mode, copy your pl executable to your cgi-bin (or make 
a link), and create a ploticus config file (see below).
The specifics of local CGI bin and file naming conventions vary;
see your local admin if having difficulty.
Then, use a construct such as this in your HTML page:
.IP
\fC<img src="http://abc.org/cgi-bin/pl?cgi=1&scat1.pl&-png&-scale&0.8&
TITLE=Trailer%20Tongue%20Technologies">\fR
.LP
This is equivalent to command line usage:
.IP
\fCpl scat1.pl  -png  -scale 0.8  TITLE="Trailer Tongue Technologies"\fR
.LP
\fCcgi=1\fR should be the first parameter in your URL construct, as shown 
in the above example.
.LP
After that, the regular 
.ig >>
<a href="pl.1.html#options">
.>>
\0pl command line options and arguments
.ig >>
</a>
.>>
, including those for
.ig >>
<a href="prefabs.html">
.>>
\0prefabs
.ig >>
</a>
.>>
,
may be given in the usual order.  However, to 
conform to URL syntax, a question mark (?) must separate the program name 
from the first argument, and ampersand (&) must be used to separate subsequent 
arguments.  Also, arguments should not be enclosed in quotes.  Use %20 to represent 
an embedded space, %26 for an embedded ampersand, etc (%XX may be used to represent 
any problematic character, where XX is its hex ascii value).  Arguments are limited 
to a length of 250 chars each and may not contain embedded newlines.  

.ig >>
<br><br><br>
.>>

.SH CGI MODE BEHAVIOR
pl automatically goes into CGI mode if it detects the environment variable 
QUERY_STRING (set by your web server), and there are no conventional command
line arguments given.  pl behaves this way when in CGI mode:

.IP \(bu
a 
.ig >>
<a href="config.html">
.>>
\0ploticus config file
.ig >>
</a>
.>>
is required, and the config file must contain a
\fCprojectroot\fR setting; other settings are optional.  
You may want to set the environment variable PLOTICUS_PREFABS via
the config file as shown.
Here is an example of a config file for CGI use:
.RS
.IP
.nf
projectroot: /home/steve/proj1
putenv:	     PLOTICUS_PREFABS=/home/steve/ploticus/prefabs
.fi
.RE
.IP
The config file
must have the same name as your pl executable, plus a \fC.cnf\fR extension
(if your pl executable name ends in \fC.cgi\fR the \fC.cgi\fR is ignored).  
If pl must be used in several different contexts within the same cgi-bin, 
you can make soft links to pl, using other names for the links, and have 
a separate config file corresponding with each one.  Examples:
.nf
        pl executable name	       use this config file name
    ---------------------------     ---------------------------
	/data/cgi-bin/pl		/data/cgi-bin/pl.cnf 
	/data/cgi-bin/plproj1		/data/cgi-bin/plproj1.cnf 
	/data/cgi-bin/pl.cgi		/data/cgi-bin/pl.cnf 
.fi
.LP
.IP \(bu
pl will operate from the \fCprojectroot\fR directory.  All filenames should
be expressed relative to \fCprojectroot\fR.  The script file must be
below projectroot.  Script file names beginning with slash (/) or 
dot (.), or containing double-dot (..) are prohibited.  This
restriction does not apply to other files (eg data files).
.LP
.IP \(bu
command arguments are extracted from QUERY_STRING (HTML POST method is not supported).
SCRIPT_FILENAME is used to build the config filename.
These are environment variables that are set by your web server before
it invokes CGI programs.
If either of these are not available, pl will exit.
.LP
.IP \(bu
default output format is GIF, JPEG, or PNG depending on the pl build;
this can also be controlled via the arguments list.
.LP
.IP \(bu
an appropriate Content-type header is generated based on output format 
type.  This header as well as image content are written to standard output.
.LP
.IP \(bu
output is limited to one image or "page".  To do multiple images, temp
files will need to be used.
.LP
.IP \(bu
pl command line options that are inappropriate in CGI mode, such as 
\fB-diagfile\fR, \fB-errfile\fR, \fB-viewer\fR, and \fB-o\fR, are disabled.
.LP
.IP \(bu
pl \fB-debug\fR automatically writes diagnostic and error info to files,
useful in troubleshooting (see below).


.ig >>
<br><br><br>
.>>

.SH TROUBLESHOOTING
Use the \fB-debug\fR option in your invoking URL, just after the \fCcgi=1\fR argument,
eg. \fChttp://abc.com/cgi-bin/pl&cgi=1&-debug&-gif\fR..
This causes error message output to be written to \fC/tmp/plcgi_err\fR 
and diagnostic output to be written to \fC/tmp/plcgi_diag\fR.
(If the config file is loaded successfully and a temp directory is specified there, then 
that directory is used instead of \fC/tmp\fR.
For win32 \fCc:\\temp\fR is the default.)
.LP
If a preliminary error occurs, such as failure to read the config file,
an error message is written to \fC/tmp/plcgi_err\fR regardless of whether \fB-debug\fR was specified.
.LP
If no error message file is appearing,
It is possible that pl was never executed.  This could be because your URL path 
is incorrect, or your web server could not access and/or execute pl because of file permissions.
To ensure your invoking URL is correct, verify by invoking some other CGI program
in the same directory.
.LP
File permissions are important.
On Unix systems,
be sure that your pl executable file mode is readable & executable by world
(use command \fCchmod 755 pl\fR) so that your web server can execute pl.
If you can, it may be desirable to set your pl executable file to be setuid and 
setgid to your own UID and group (\fCchmod 6755 pl\fR); then it will be able to see all 
files that you can see.  Otherwise, pl will execute as your web server UID (often \fCnobody\fR), 
and you'll need to ensure that your config file and all other files needed such as 
script files, data files, and prefabs files are readable by world, so that your
web server process can gain access (\fCchmod 644 \fIfilenames\fR).
If you're using symbolic links, file permissions generally must be set on the actual file, not the link.
.LP
Another thing to try is to simulate CGI invocation from the command line.
To do this, \fCcd\fR to your cgi bin, deploy a new term window, and in the new window
manually set the QUERY_STRING and SCRIPT_FILENAME environment variables,
eg:
.IP
\fCexport QUERY_STRING="scat1.pl&-scale&0.8"\fR
.IP
\fCexport SCRIPT_FILENAME="/data/cgi-bin/pl"
.LP
Full pathname should be given in SCRIPT_FILENAME so that pl can locate its config file.
If you want your CGI to generate PNG you may need to place \fCplpng\fR into your 
cgi-bin and execute it instead of \fCpl\fR (this depends on your ploticus build).
.LP
Then, in the new window, invoke pl by hand, with no command line arguments:
.IP
\fC$SCRIPT_FILENAME > out\fR
.LP
Any error messages should be visible on screen.  
(The output file will generally not be displayable because it contains a mime-type header.)
.LP
In theory CGI mode should work with PNG, GIF, JPEG and SVG.
I noticed some flakiness with SVG.  If the pl script argument was
last and I was generating SVG, MSIE wouldn't display it until I added a trailing \fC&\fR
to the URL.  And, MSIE didn't understand SVGZs when generated in CGI mode.

.ig >>
<a name=security></a>
.>>
.ig >>
<br><br><br>
.>>

.SH CGI SECURITY 
.LP
You should be fully familiar with CGI security issues and how
they relate to your platform and project,
before putting pl into
service as a CGI program.  
Some things to keep in mind:
.IP \(bu
Anyone can easily view your HTML, including your invocation of CGI programs.
It is also very easy for users to submit modified CGI invocations (especially altered
arguments).
.IP \(bu
If you pass a data file name (or other filename) to pl via a varvalue argument, 
use the following within your pl script to guard against hacks on the file name:
.RS
.IP
.nf
\0 #if @DATAFILE inlike /*,.*,*..*
\0   #exit
\0 #endif
.fi
.RE
.IP \(bu
If you build a shell command from anything passed via a varvalue argument, 
remove shell metacharacters from the variables using the 
.ig >>
<a href="shell.html">
.>>
\0$shellstripchars function
.ig >>
</a>
.>>
\0.
.IP \(bu
It is possible that undiscovered security holes exist with ploticus in direct CGI mode.
If you will lose sleep over this,
see the discussion on
.ig >>
<a href="dynamic.html">
.>>
\0on-the-fly graphics
.ig >>
</a>
.>>
for alternatives.
.LP
\fBNote:\fR A CGI-related security hole was uncovered Feb 8 '02 and 
affects versions 2.00, 2.01, and 2.02.
See
.ig >>
<a href="http://ploticus.sourceforge.net/doc/Versions.html">
.>>
\0what's new page
.ig >>
</a>
.>>
to upgrade or apply patch.
.ig >>
<br><br><br>
.>>

.ig >>
<br>
<br>
</td></tr>
<td align=right>
<a href="../doc/Welcome.html">
<img src="../doc/ploticus.gif" border=0></a><br><small>data display engine &nbsp; <br>
<a href="../doc/Copyright.html">Copyright Steve Grubb</a>
<br>
<br>
<center>
<img src="../gallery/all.gif">
</center>
</td></tr>
</table>
.>>
