1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
|
<html>
<head>
<!-- This file has been generated by unroff 1.0, 03/05/02 11:05:55. -->
<!-- Do not edit! -->
<STYLE TYPE="text/css">
<!--
A:link{text-decoration:none}
A:visited{text-decoration:none}
A:active{text-decoration:none}
-->
</STYLE>
<title>ploticus: operating in 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>Operating in 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>
<a href="../gallery/index.html">Gallery</a>
<a href="../doc/Contents.html">Handbook</a>
<td></tr></table>
</td></tr>
<td>
<br>
<br>
<title>Manual page for Operating_in_CGI_mode(PL)</title>
</head>
<body>
<h2>INVOKING PL AS A CGI PROGRAM</h2>
As of version 2.00,
<a href="pl.1.html">
pl
</a>
may be invoked directly as a CGI program, to dynamically
create plots without having to write images to temp files.
Direct CGI mode can produce pseudo-GIF, PNG, JPEG,
<a href="svg.html">
SVG or SVGZ.<tt> </tt>
</a>
<p>
<b>Note:</b> A CGI-related security hole was uncovered Feb 8 '02 and
affects versions 2.00, 2.01, and 2.02.<tt> </tt>
See
<a href="http://ploticus.sourceforge.net/doc/Versions.html">
what's new page
</a>
to upgrade or apply patch.<tt> </tt>
<br><br><br>
<p>
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).<tt> </tt>
The specifics of local CGI bin and file naming conventions vary;
see your local admin if having difficulty.<tt> </tt>
Then, use a construct such as this in your HTML page:
<dl>
<dt><dd><p>
<tt><img src="http://abc.org/cgi-bin/pl?cgi=1&scat1.pl&-png&-scale&0.8&
TITLE=Trailer%20Tongue%20Technologies"></tt>
</dl>
<p>
This is equivalent to command line usage:
<dl>
<dt><dd><p>
<tt>pl scat1.pl -png -scale 0.8 TITLE="Trailer Tongue Technologies"</tt>
</dl>
<p>
<tt>cgi=1</tt> should be the first parameter in your URL construct, as shown
in the above example.<tt> </tt>
<p>
After that, the regular
<a href="pl.1.html#options">
pl command line options and arguments
</a>
, including those for
<a href="prefabs.html">
prefabs
</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.
<br><br><br>
<h2>CGI MODE BEHAVIOR</h2>
pl automatically goes into CGI mode if it detects the environment variable
REQUEST_URI (set by your web server), and there are no conventional command
line arguments given. pl behaves this way when in CGI mode:
<ul>
<li>
a
<a href="config.html">
ploticus config file
</a>
is required, and the config file must contain a
<tt>projectroot</tt> setting; other settings are optional.
You may want to set the environment variable PLOTICUS_PREFABS via
the config file as shown.<tt> </tt>
Here is an example of a config file for CGI use:
</ul>
<dl><dt><dd>
<dl>
<dt><dd><p>
<pre>
projectroot: /home/steve/proj1
putenv: PLOTICUS_PREFABS=/home/steve/ploticus/prefabs
</pre>
</dl>
</dl>
<dl>
<dt><dd><p>
The config file
must have the same name as your pl executable, plus a <tt>.cnf</tt> extension
(if your pl executable name ends in <tt>.cgi</tt> the <tt>.cgi</tt> 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:
<pre>
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
</pre>
</dl>
<p>
<ul>
<li>
pl will operate from the <tt>projectroot</tt> directory. All filenames should
be expressed relative to <tt>projectroot</tt>. 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).<tt> </tt>
</ul>
<p>
<ul>
<li>
command arguments are extracted from REQUEST_URI (HTML POST method is not supported).<tt> </tt>
SCRIPT_FILENAME is used to build the config filename.<tt> </tt>
These are environment variables that are set by your web server before
it invokes CGI programs.<tt> </tt>
If either of these are not available, pl will exit.<tt> </tt>
</ul>
<p>
<ul>
<li>
default output format is GIF, JPEG, or PNG depending on the pl build;
this can also be controlled via the arguments list.<tt> </tt>
</ul>
<p>
<ul>
<li>
an appropriate Content-type header is generated based on output format
type. This header as well as image content are written to standard output.<tt> </tt>
</ul>
<p>
<ul>
<li>
output is limited to one image or "page". To do multiple images, temp
files will need to be used.<tt> </tt>
</ul>
<p>
<ul>
<li>
pl command line options
<b>-diagfile</b>, <b>-errfile</b>, and <b>-viewer</b> do not do anything.<tt> </tt>
</ul>
<p>
<ul>
<li>
pl <b>-debug</b> automatically writes diagnostic and error info to files,
useful in troubleshooting (see below).<tt> </tt>
<br><br><br>
</ul>
<h2>TROUBLESHOOTING</h2>
If -debug is specified, diagnostic output is written to <tt>/tmp/plcgi_diag</tt>
and error message output is written to <tt>/tmp/plcgi_err</tt> .. This should be
helpful with debugging in CGI mode (if the user specifies a tmpdir then
that directory is used; for win32 c:\temp is the default).<tt> </tt>
<p>
Another technique would be to simulate CGI invocation from the command line.<tt> </tt>
TO do this, <tt>cd</tt> to your cgi bin, deploy a new term window, and in the new window
manually set the REQUEST_URI and SCRIPT_FILENAME environment variables,
eg:
<dl>
<dt><dd><p>
<tt>export REQUEST_URI="cgi-bin/pl?scat1.pl&-scale&0.8"</tt>
<dt><dd><p>
<tt>export SCRIPT_FILENAME="/data/cgi-bin/pl"
</tt></dl>
<p>
These exact variable names should be used.<tt> </tt>
REQUEST_URI should be the full URL, less the <tt>http://</tt><i>hostname</i> prefix.<tt> </tt>
Full pathname should be given in SCRIPT_FILENAME so that pl can locate its config file.<tt> </tt>
If you want your CGI to generate PNG you may need to place <tt>plpng</tt> into your
cgi-bin and execute it instead of <tt>pl</tt> (this depends on your ploticus build).<tt> </tt>
<p>
Then, in the new window, invoke pl by hand, with no command line arguments:
<dl>
<dt><dd><p>
<tt>$SCRIPT_FILENAME > out</tt>
</dl>
<p>
Any error messages should be visible on screen.
<p>
In theory CGI mode should work with PNG, GIF, JPEG and SVG.<tt> </tt>
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 <tt>&</tt>
to the URL. And, MSIE didn't understand SVGZs when generated in CGI mode.<tt> </tt>
<br><br><br>
<h2>CGI SECURITY</h2>
<p>
<b>Note:</b> A CGI-related security hole was uncovered Feb 8 '02 and
affects versions 2.00, 2.01, and 2.02.<tt> </tt>
See
<a href="http://ploticus.sourceforge.net/doc/Versions.html">
what's new page
</a>
to upgrade or apply patch.<tt> </tt>
<br><br><br>
<p>
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:
<ul>
<li>
Anyone can easily view your HTML, including your invocation of CGI programs.<tt> </tt>
It is also very easy for users to submit modified CGI invocations (especially altered
arguments).<tt> </tt>
<li>
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:
</ul>
<dl><dt><dd>
<dl>
<dt><dd><p>
<pre>
#if @DATAFILE inlike /*,.*,*..*
#exit
#endif
</pre>
</dl>
</dl>
<ul>
<li>
If you build a shell command from anything passed via a varvalue argument,
remove shell metacharacters from the variables using the
<a href="shell.html">
$shellstripchars function
</a>
.<tt> </tt>
<li>
It is possible that undiscovered security holes exist with ploticus in direct CGI mode.<tt> </tt>
CGI security worries can be avoided by invoking ploticus via the shell (ie. the old way),
capturing the results into a temp file, then using <img> to access the temp file.<tt> </tt>
The tradeoff is that this is less efficient due the temp file i/o.<tt> </tt>
</ul>
<p>
<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 <br>
<a href="../doc/Copyright.html">Copyright Steve Grubb</a>
<br>
<br>
<center>
<img src="../gallery/all.gif">
</center>
</td></tr>
</table>
<p><hr>
Markup created by <em>unroff</em> 1.0, <tt> </tt> <tt> </tt>March 05, 2002.
</body>
</html>
|
