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