File: cgi.html

package info (click to toggle)
ploticus-doc 2.40-1
  • links: PTS
  • area: main
  • in suites: lenny
  • size: 9,604 kB
  • ctags: 159
  • sloc: pascal: 469; makefile: 63; sh: 11
file content (359 lines) | stat: -rw-r--r-- 13,487 bytes parent folder | download
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
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
<html>
<head>
<!-- This file has been generated by unroff 1.0, 01/15/08 14:06:23. -->
<!-- Do not edit! -->
<STYLE TYPE="text/css">
<!--
        A:link{text-decoration:none}
        A:visited{text-decoration:none}
        A:active{text-decoration:none}
        OL,UL,P,BODY,TD,TR,TH,FORM { font-family: arial,helvetica,sans-serif;; font-size:small; color: #333333; }

        H1 { font-size: x-large; font-family: arial,helvetica,sans-serif; }
        H2 { font-size: large; font-family: arial,helvetica,sans-serif; }
        H3 { font-size: medium; font-family: arial,helvetica,sans-serif; }
        H4 { font-size: small; font-family: arial,helvetica,sans-serif; }
-->
</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>
  Version 2.40 Jan'08
  <td></tr></table>
</td></tr>
<td>
<br>
<br>

<title>Manual page for Direct_CGI_mode(PL)</title>
</head>
<body>


<p>
<a href="pl.1.html">
 pl
</a>
may be invoked from within an HTML <tt>&lt;img&gt;</tt> tag as a CGI program to create plots on the fly.<tt> </tt>
Direct CGI mode can produce PNG, JPEG, and other web browser displayable formats.<tt> </tt>
This is one of several possible ways to implement 
<a href="dynamic.html">
 just-in-time charting.<tt> </tt>
</a>

<br><br><br>
<h2>Security concerns</h2>
<p>

Please be sure you understand the various
<a href="#security">
 CGI-related security concerns discussed below
</a>
that come into play when using ploticus in direct CGI mode.<tt> </tt>
<p>
In particular, note that
<a href="prefabs.html">
 prefabs
</a>
are unsafe in direct CGI mode (and in any other situation
where unknown/untrusted users can directly or indirectly set or manipulate prefab parameters).<tt> </tt>

<br><br><br>

<h2>Quick start</h2>
<p>
Briefly, here's what you need to do to use ploticus in direct CGI mode:
<p>
1. be sure you understand the
<a href="#security">
 CGI-related security concerns
</a>
<p>
2. copy your pl executable to your cgi-bin (or perhaps create a soft link)
<p>
3. using a text editor, create a ploticus config file in your cgi-bin.  This allows ploticus to get its bearings and find things (discussed below)
<p>
4. check file and directory permissions - be sure that your web server (which typically runs as a UID of <tt>nobody</tt>) can
access your pl executable, config file, data file, and script file 
<p>
5. place an &lt;IMG&gt; construct into your HTML page that uses an appropriate URL (discussed below)
<p>
6. point your web browser to the HTML page.. this will cause pl to be executed and
if everything's working you will see the graphic result
<p>
7. If you're not getting the desired results, add the <tt>-debug</tt> option in your invoking URL, like this:
<tt>/cgi-bin/pl&amp;cgi=1&amp;-debug&amp;-gif </tt>..  This causes error messages to be logged to <tt>/tmp/plcgi_err</tt>
and debug output to <tt>/tmp/plcgi_diag</tt> .<tt> </tt>
<p>
8. See the other
<a href="#troubleshooting">
 troubleshooting tips below
</a>

<br><br><br>

<h2>Config file</h2>
Because CGI programs are invoked in a generic, bare-bones environment, you must provide
some basic information so that ploticus can get its bearings and find necessary files.<tt> </tt>
This is done by creating a <tt>config file</tt> (not the same thing as a <tt>script file</tt>).<tt> </tt>
It can be created using a text editor.<tt> </tt>
It must be located in your cgi-bin and named similarly to your <b>pl</b> executable.. eg. if your
pl executable is named <tt>pl</tt> or <tt>pl.exe</tt> your config file must be named <tt>pl.cnf</tt>.<tt> </tt>
<p>
Here's an example of a minimal config file for ploticus in CGI mode:
<pre>
	projectroot: /home/steve/proj1
</pre>
<p>
<b>projectroot</b> specifies a directory where ploticus will execute and do its work.<tt> </tt>
It must be a directory accessible by your local web server.<tt> </tt>
Data file names and script file names should be expressed relative to <b>projectroot</b>.<tt> </tt>
If you're using your own ploticus script it must reside within the <b>projectroot</b> 
directory or one of its subdirectories.  
<p>
Don't set PLOTICUS_PREFABS here!  See 
<a href="#security">
 security concerns, below.<tt> </tt>
</a>
<p>
There are many other optional things that can be done as well ...<tt> </tt>
<a href="config.html">
 more about config files.<tt> </tt>
</a>

<br><br><br>

<h2>URLs</h2>
In direct CGI mode you invoke ploticus using a URL instead of command line.<tt> </tt>
Fortunately the two methods are similar, varying only in argument delimitation syntax.<tt> </tt>
Here are two examples:
<p>
<p>
<b>Example command:</b> <tt>pl scat1.pl  -png  TITLE="Usage report"  -scale 0.8</tt>
<br>
<b>URL equivalent:</b> <tt>&lt;img src="/cgi-bin/pl?cgi=1&amp;scat1.pl&amp;-png&amp;TITLE=Usage%20report&amp;-scale&amp;0.8"&gt;</tt>


<br><br>

<p>
<b>Here are the rules for URLs:</b>
<p>
1. the first part of the URL locates your cgi-bin, eg.<tt> </tt>
<tt>http://abc.com/cgi-bin</tt> or just <tt>/cgi-bin</tt> (relative)
and the program to execute (<tt>pl</tt>) .. of course this part is dependent on local configuration.<tt> </tt>
A question mark (<tt>?</tt>) must follow the program name.  This is all standard CGI practice.<tt> </tt>
<p>
2. The first argument after the question mark should be <tt>cgi=1</tt>.<tt> </tt>
This helps make it clear to <tt>pl</tt> that it is operating as a CGI program.<tt> </tt>
<p>
3. Next come all the other pl arguments and parameters.<tt> </tt>
Just about any set of 
<a href="pl.1.html#options">
 ploticus command line arguments
</a>
can be used, in the usual order.<tt> </tt>
Each argument is delimited using an ampersand (<tt>&amp;</tt>).<tt> </tt>
Some command line arguments, such as 
<tt>-scale 0.8</tt> are really two arguments, and must
be treated as such for URL purposes (see examples above).<tt> </tt>
Arguments that need to be quoted when used on the command line should <b>not</b> be quoted in URL usage.<tt> </tt>
Standard URL encoding may be used to represent problematic characters such as spaces (<tt>%20</tt>), ampersands (<tt>%26</tt>), etc.<tt> </tt>
Arguments are truncated to a length of 250 chars each.<tt> </tt>
<p>
Note: any settings that apply to all your invocations can be conveniently made in your 
<a href="config.html">
 config file
</a>
using the <tt>option:</tt> or <tt>varvalue:</tt> directives.  This also gets them out of the public eye.<tt> </tt>


<br><br><br>
<h2>Notes</h2>
<p>
<b>pl</b> senses that it is running as a CGI program automatically if it finds the environment variable 
QUERY_STRING (set by your web server), and there are no conventional command line arguments present.<tt> </tt>
Command arguments are extracted from QUERY_STRING environment variable.<tt> </tt>
Providing the <tt>cgi=1</tt> dummy argument helps in cases where there are no other CGI user arguments.<tt> </tt>
<p>
Default output format will be PNG, JPEG, or GIF depending on the pl build.<tt> </tt>
An appropriate HTTP <tt>Content-type</tt> header is generated (based on output format type) and written to standard output.  
<p>
HTTP POST method is not supported.<tt> </tt>
<p>
You can only generate one image per invocation in direct CGI mode.<tt> </tt>
<p>
Clickmaps generally cannot be done in direct CGI mode, since the map and the image content require
two separate streams.<tt> </tt>
<p>
Command line options that are inappropriate in direct CGI mode, such as 
<tt>-diagfile</tt>, <tt>-errfile</tt>, <tt>-viewer</tt>, and <tt>-o</tt>, are automatically disabled.<tt> </tt>
<p>
I noticed some flakiness with SVG in direct CGI mode.<tt> </tt>

<a name=troubleshooting></a>
<br><br><br>

<h2>Troubleshooting</h2>
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).<tt> </tt>
<p>
The first thing to try is to use the <b>-debug</b> option in your invoking URL, like this:
<tt>http://abc.com/cgi-bin/pl&amp;cgi=1&amp;-debug&amp;-gif</tt>..<tt> </tt>
This will cause error messages to be logged to <tt>/tmp/plcgi_err</tt>
and additional diagnostic output to be logged to <tt>/tmp/plcgi_diag</tt> .<tt> </tt>

<br><br>

<p>
<b>Things to check:</b>
<ul>
<li>
Be sure that at least one of the above files exists.  
If not, then pl probably was never invoked by your web server.. indicating an incorrect URL, or
a problem where your web server is not able to get or execute <b>pl</b>.<tt> </tt>
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.<tt> </tt>
For example, on some installations the web server can't access any file located outside of the web tree.<tt> </tt>
(Note: Win32 uses <tt>c:\temp</tt>.  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).<tt> </tt>

<br><br>

<li>
File permissions are important.<tt> </tt>
On Unix systems, be sure that your pl executable file mode is readable &amp; executable by world
(use command <tt>chmod 755 pl</tt>) so that your web server (which typically executes as a
generic UID such as <tt>nobody</tt>) can get and execute pl.<tt> </tt>
Be sure that all other necessary files and directories
(your config file, data file, and script file)
If you're using symbolic links, file permissions generally must be set on the actual file, not the link.<tt> </tt>

<br><br>
<li>
Another thing to try is 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 QUERY_STRING environment variable,
eg:
<br>
<tt>export QUERY_STRING="scat1.pl&amp;-scale&amp;0.8"</tt>
<br>
Then, in the new window, invoke pl by hand, with no command line arguments, similarly to this:
<br>
<tt>/data/htdocs/cgi-bin/pl &gt; out</tt>
<br>
Any error messages should be visible on screen.  
(The output file will generally not be displayable because it contains a mime-type header.)

<br><br>
<li>
If you built ploticus with both GIF and PNG enabled, and 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>.<tt> </tt>


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

</ul>
<h2>CGI security</h2>
<p>
<a href="prefabs.html">
 Prefabs
</a>
are unsafe in 
<a href="cgi.html">
 direct CGI mode
</a>
and in any other situation
where unknown/untrusted users can directly or indirectly set or manipulate prefab parameters.<tt> </tt>
<p>
When operating in direct cgi mode and similar situations 
script writers should be sure that prefabs are disabled.  In version 2.32 and later prefabs should
be automatically disabled in direct cgi mode.<tt> </tt>
Do not set the <tt>PLOTICUS_PREFABS</tt> environment variable in the config file.<tt> </tt>
Prefabs may also be disabled by simply renaming the <tt>prefabs</tt> directory to some other name, or removing it.<tt> </tt>
<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>
<br><br>
<li>
Avoid building filenames from user-supplied values such as CGI user variables.<tt> </tt>
Where there's no alternative, proper measures including the following should be
used to guard against hacks on the file name:
<pre>
  #if @DATAFILE inlike /*,.*,*..*
    #exit
  #endif
</pre>
<br><br>
<li>
Avoid using <tt>#shell</tt> in your scripts that will run in direct CGI mode.<tt> </tt>
<br><br>
<li>
If you build a shell command using CGI user variables and execute it using the
<a href="plshellsql.html">
 #shell
</a>
directive, embedded metacharacters that could be used to carry out malicious activity should
automatically be screened out from the shell command.  The developer should verify that
this is working as expected.<tt> </tt>
<br><br>
<li>
It is possible that undiscovered security holes exist with ploticus in direct CGI mode.<tt> </tt>
If you will lose sleep over this, consider one of the other methods for
<a href="dynamic.html">
 just-in-time charting.<tt> </tt>
</a>

<br><br><br>
</ul>
<h2>Using ploticus CGI with ASP/VBS</h2>
This is discussed here:
<a href="http://groups.yahoo.com/group/ploticus/message/1358">
 ploticus newsgroup message# 1358
</a>



<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>
<br>
<center>
Ploticus is hosted at http://ploticus.sourceforge.net <br>
<img src="http://sourceforge.net/sflogo.php?group_id=38453" width="88" height="31" border="0" alt="SourceForge Logo">
</center>
<p><hr>
Markup created by <em>unroff</em> 1.0,&#160;<tt> </tt>&#160;<tt> </tt>January 15, 2008.
</body>
</html>