Direct CGI mode |

Version 2.30
| |
|
Manual page for Direct_CGI_mode(PL)
Direct CGI mode
pl
may be invoked directly from URLs in HTML pages, to create plots on the fly.
Direct CGI mode can produce pseudo-GIF, PNG, JPEG,
SVG or SVGZ.
Caution: there are some
CGI-related security concerns
that must be fully understood before using pl in direct CGI mode.
In addition to direct CGI mode there are several other good ways to implement just-in-time
charting with ploticus, discussed
here.
To use ploticus in direct CGI mode, copy your pl executable to your cgi-bin (or perhaps create
a soft 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:
-
-
<img src="http://abc.org/cgi-bin/pl?cgi=1&scat1.pl&-png&-scale&0.8&
TITLE=Trailer%20Tongue%20Technologies">
This is equivalent to command line usage:
-
-
pl scat1.pl -png -scale 0.8 TITLE="Trailer Tongue Technologies"
cgi=1 should be the first parameter in your URL construct, as shown
in the above example.
After that, the regular
pl command line options and arguments
, including those for
prefabs
,
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.
Direct CGI mode behavior
pl automatically goes into direct 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:
-
a
ploticus config file
is required, and the config file must contain a
projectroot 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 direct CGI mode:
-
projectroot: /home/steve/proj1
putenv: PLOTICUS_PREFABS=/home/steve/ploticus/prefabs
The config file
must have the same name as your pl executable, plus a .cnf extension
(if your pl executable name ends in .cgi or .exe these are removed before appending
the .cnf).
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:
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
/data/cgi-bin/pl.exe /data/cgi-bin/pl.cnf
-
pl will operate from the projectroot directory. All filenames should
be expressed relative to projectroot. 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).
-
command arguments are extracted from QUERY_STRING
which is an environment variable set by your web server before it invokes CGI programs.
(HTML POST method is not supported).
If this is not available, pl will exit.
-
default output format is GIF, JPEG, or PNG depending on the pl build;
this can also be controlled via the arguments list.
-
an appropriate HTTP Content-type header is generated based on output format
type. This header as well as image content are written to standard output.
-
output is limited to one image or "page". To do multiple images, temp
files will need to be used.
-
pl command line options that are inappropriate in direct CGI mode, such as
-diagfile, -errfile, -viewer, and -o, are disabled.
-
pl -debug automatically writes diagnostic and error info to files,
useful in troubleshooting (see below).
Troubleshooting
Getting direct CGI mode to work can be tricky... and certain details depend on your
local web server configuration. Ploticus direct CGI mode should work on any server
that supports the CGI standard (almost all do).
Here are some things to try if you're having trouble:
Use the -debug option in your invoking URL, like this:
http://abc.com/cgi-bin/pl&cgi=1&-debug&-gif..
Error messages will be written to /tmp/plcgi_err .
Debug output will be written to /tmp/plcgi_diag .
Check to see if at least one of these files exists. If not, then pl probably was never invoked by your web server.
Try invoking pl (or better yet, some other program in your cgi-bin) directly by typing a URL into your web browser.
Your local webmaster or sysadmin team can help.
For example, on some installations the web server can't access any file located outside of the web tree.
(Note: Win32 uses c:\temp. Also,
if you specified a different temp directory in your ploticus config file, diagnostic
files may be placed there, if pl was able to read your config file).
Other things to check:
-
File permissions are important.
On Unix systems, be sure that your pl executable file mode is readable & executable by world
(use command chmod 755 pl) so that your web server can execute pl.
You may want to chmod your pl executable file to be setuid and
setgid to your own UID and group (chmod 6755 pl); then it will be able to see all
files that you can see. Otherwise, pl will execute as your web server UID (often nobody),
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 (chmod 644 filenames).
If you're using symbolic links, file permissions generally must be set on the actual file, not the link.
-
Another thing to try is to simulate CGI invocation from the command line.
To do this, cd to your cgi bin, deploy a new term window, and in the new window
manually set the QUERY_STRING environment variable,
eg:
export QUERY_STRING="scat1.pl&-scale&0.8"
Then, in the new window, invoke pl by hand, with no command line arguments, similarly to this:
/data/htdocs/cgi-bin/pl > out
Any error messages should be visible on screen.
(The output file will generally not be displayable because it contains a mime-type header.)
-
If you built ploticus with both GIF and PNG enabled, and want your CGI to generate PNG,
you may need to place plpng into your cgi-bin and execute it instead of pl.
Other issues
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 &
to the URL. And, MSIE didn't understand SVGZs when generated in CGI mode.
CGI security
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:
-
If you build a shell command using CGI user variables and execute it using the
#shell
directive, embedded metacharacters that could be used to carry out malicious activity are
automatically screened out from the shell command. The developer should verify that
this is working as expected.
-
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
on-the-fly graphics
for alternatives.
|
 data display engine
Copyright Steve Grubb
|