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
|
<html>
<head>
<!-- This file has been generated by unroff 1.0, 09/17/01 08:34:40. -->
<!-- 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: shell</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>SHELL</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 SHELL(PL)</title>
</head>
<body>
<h2>
<tt>#shell </tt><i>option</i><tt> </tt><i>command</i><tt> [#endshell]
<br><br><br>
</tt><hr></h2>
<h2>DESCRIPTION</h2>
Execute the given shell <i>command</i>, and optionally display or
capture the results.<tt> </tt>
An <i>option</i> may be given; available
options (described below) are
<tt>#dump</tt> (the default),
<tt>#processrows</tt>,
<tt>#dumptab</tt>, <tt>#dumphtml</tt>, and <tt>#dumpsilent</tt>.<tt> </tt>
<p>
<i>command</i> may use a single line construct or a
multi-line construct formatted as in example 3 below.
<tt>#endshell</tt> must be used to terminate a multi-line construct.<tt> </tt>
<p>
The command's exit status is available in
the @_STATUS script variable; 0 generally indicates
success.<tt> </tt>
<p>
<a href="plshellsql.html">
Using #shell in ploticus scripts
</a>
<h2>EXAMPLES</h2>
<p>
Example 1: <tt>#shell date</tt>
<p>
Example 2:
<dl>
<dt><dd><p>
<pre>
#shell rm /tmp/myfile*
#if @_STATUS != 0
Command failed.
#endif
</pre>
</dl>
<p>
Example 3:
<dl>
<dt><dd><p>
<pre>
#shell
cat /etc/vstab |
grep "^afx"
#endshell
</pre>
</dl>
<h2>OPTIONS</h2>
An <i>option</i> may be given to specify how command results should
be displayed or captured. If no option is given, <tt>#dump</tt> is
done by default.<tt> </tt>
The options all begin with a pound sign (#) so as not to be confused with
command content.<tt> </tt>
<p>
<b>#dump</b>
<dl>
<dt><dd><p>
Display all results immediately without any processing.<tt> </tt>
Example:
<pre>
#shell #dump ls -l
</pre>
</dl>
<p>
<b>#dumptab</b>
<dl>
<dt><dd><p>
Display all results immediately in tab-delimited field format.<tt> </tt>
Fields will be parsed in each result line, then the fields
will be displayed separated by tabs.<tt> </tt>
Use the
<a href="functions.html#shell">
$shellfielddelim() function
</a>
to control shell result field parsing.<tt> </tt>
Example:
<pre>
#shell #dumptab
cat mydata | grep "^Jan"
#endshell
</pre>
</dl>
<p>
<b>#dumphtml</b>
<dl>
<dt><dd><p>
Display all results immediately in HTML table row format.<tt> </tt>
Fields will be parsed in each result line, then the fields
will be displayed separated by tabs.<tt> </tt>
Use the
<a href="functions.html#shell">
$shellfielddelim() function
</a>
function to control shell result field parsing.<tt> </tt>
</dl>
<p>
<b>#dumpsilent</b>
<dl>
<dt><dd><p>
all rows of results will be retrieved then discarded. Used to
get a count of the number of rows.<tt> </tt>
Example:
<pre>
#shell #dumpsilent cat mydata | grep "^Jan"
#set N = $shellrowcount()
</pre>
</dl>
<p>
<b>#processrows</b>
<dl>
<dt><dd><p>
Indicates that results will be retrieved and processed later
one line at a time using the <tt>$shellrow()</tt>
<a href="functions.html#shell">
function
</a>
. When processing rows, retrieved fields are available as script variables.<tt> </tt>
Example:
<dt><dd><p>
<pre>
#shell #processrows cat mydata | grep "^Jan"
#if @_STATUS != 0
Command error @_STATUS.
#exit
#endif
// get the result rows..
#while $shellrow( A, B, C) = 0
// now access the fields as variables..
#if @B = 1
...etc..
#endloop
<br><br><br>
</pre>
</dl>
<h2>SHELL-RELATED FUNCTIONS</h2>
The following functions are related to
the execution of shell commands.<tt> </tt>
<p>
<b>$shellrow( args )</b>
<dl>
<dt><dd><p>
Read one line of shell command results, and perhaps parse into fields.<tt> </tt>
Returns 0 on success, 1 if no more result lines, or an error code > 1.<tt> </tt>
<i>args</i> may be passed in one of several forms.<tt> </tt>
If <i>args</i> is a comma-delimited list of variable names, these variables
will be set to values of parsed fields. If <i>args</i> is <tt>#varvaluepair</tt>
the first parsed field will be taken as a variable name and the second field as
the value (any trailing colon (:) will be removed from the variable name).<tt> </tt>
No <i>args</i> should be supplied if the command generates a field name
header.<tt> </tt>
<dt><dd><p>
Example 1: <tt>#set STAT = $shellrow( name, address, phone )</tt>
<dt><dd><p>
Example 2: <tt>#set STAT = $shellrow( #varvaluepair )</tt>
<dt><dd><p>
Code example (assume that the given shell command produces three
whitespace delimited fields (date, action, description):
<pre>
#call $shellfielddelim( whitespace )
#shell cat mydata | grep "^Jan"
#loop
#set STAT = $shellrow( DATE, ACTION, DESC )
#if @STAT != 0
#break
#endif
...
</pre>
</dl>
<p>
<b>$shellrowcount()
</b><dl>
<dt><dd><p>
Return the number of rows resulting from the most recent #shell command,
that were processed.<tt> </tt>
<dt><dd><p>
Example: <tt>#set N = $shellrowcount()</tt>
</dl>
<p>
<b>$shellreadheader()
</b><dl>
<dt><dd><p>
For shell commands that generate a field name header, this function
loads the header. It should be called before $shellrow().
<dt><dd><p>
Example:
<pre>
#call $shellfielddelim( tab )
#shell mycommand
#call $shellreadheader
#loop
#set STAT = $shellrow()
#if @STAT != 0
#break
#endif
...
#endloop
</pre>
</dl>
<p>
<b>$shellfielddelim( s )</b>
<dl>
<dt><dd><p>
Set the delimitation method for parsing shell command result fields.<tt> </tt>
Allowable values for <i>s</i>
are <tt>tab</tt>, <tt>whitespace</tt>, or <tt>line</tt> (which takes the entire
line, sans newline, as a field). Default is <tt>line</tt>.<tt> </tt>
<dt><dd><p>
Example: <tt>#call shellfielddelim( whitespace )</tt>
</dl>
<p>
<b>$shellstripchars( chars, varname1, .. varnameN )</b>
<dl>
<dt><dd><p>
Remove shell metacharacters (etc.) from user-supplied variables
that are to be used to build a shell command to stop hackers from
entering character combinations that would let them invoke their own
shell commands.
See the discussion of
<a href="#security">
cgi shell security concerns
</a>
for more information.<tt> </tt>
<i>chars</i> is a set of characters to be removed.<tt> </tt>
<i>chars</i> may be omitted; in this case
a basic set of exploitable characters (<tt> ", ', `, $, \, and ; </tt>) will be
removed from variables (see example 1).<tt> </tt>
<i>varname</i>s are the names of variable(s) from which the
dangerous characters will be removed.<tt> </tt>
<dt><dd><p>
Example 1: <tt>#call $shellstripchars( NAME, ADDRESS )</tt>
<dt><dd><p>
Example 2: <tt>#call $shellstripchars( "\"'`\$*();|^", NAME, ADDRESS, PHONE )</tt>
<a name=security></a>
<br><br><br>
</dl>
<h2>SECURITY CONCERNS</h2>
[Note: the following information is offered only a guide; developers are
completely responsible for fully examining and understanding
the security of their own systems.]
<p>
A security risk exists when user-supplied values are used
to build shell commands.<tt> </tt>
Devious users can enter input that, unless precautions
are taken, can cause the shell to execute other commands.
For example, suppose a program takes a user search string
and uses it to build a grep command:
<dl>
<dt><dd><p>
<pre>
#cgivar SEARCH
#shell grep "@SEARCH" /data/*
</pre>
</dl>
<p>
A devious user could enter something like this: <tt>foo" /etc/passwd; rm *; echo "hi</tt>
and remove all files in the program's current directory.<tt> </tt>
<p>
This security hole is especially relevant to
CGI programs, which are often accessible by
the world, and may run in priveledged mode.<tt> </tt>
<p>
To limit this security hole:
1) remove characters that could be exploited (I would start with
these:<tt> " ' ` $ \ ; </tt>)
from variables that will be used to build shell commands
(the function
<a href="functions.html#shell">
$shellstripchars()
</a>
is available for doing this);
2) enclose all user-supplied variables in double quotes in the shell command
<br>
<br>
</td></tr>
<td align=right>
<a href="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>September 17, 2001.
</body>
</html>
|
