Shell Command Filter

Definition

Description

If event matches Condition execute Expression as a shell command using Shell and set FieldName with its output, FieldName to its error output and FieldName to its return status.

 

 

Comments

If Expression or Shell is missing, blank or invalid, the filter will be disabled.

If the first FieldName is missing, blank or invalid, make its default ev:msg. If the other FieldName parameters are missing, blank or invalid, do not set their values.

When the shell command completes, the event is released into the stream after creating the following event fields:

ev:shellCommand.StartTime = StartingTime
ev:shellCommand.EndTime = EndingTime
ev:shellCommand.ExecutionSecs = time in seconds for shell command to execute
ev:shellCommand.CommandString = the shell command string that was executed
ev:shellCommand.ProcessId = process ID, if available

Only one command shell will be executing at a given time. The prior command shell must complete its execution before the next event can be processed, possibly filling up the incoming event queue if shell execution is slower than event arrival.

Typically, Shell is set to "/bin/sh –c" for Linux and "C:\cmd.exe \C" for Windows, allowing for execution of multiple commands in Expression. Under Linux, the commands will execute using the uid and environment of the ECS and '/' as its current working directory, and under Windows the command will execute with 'C:\' as its working directory and the privileges of the ECS process.

 

Example

<filter objectId="ShellCommand.one" type="ShellCommandFilter">
	<parameter type="Condition">
		<negatePrimaryCondition>false</negatePrimaryCondition>
		<conditionRelation>Any</conditionRelation>
	</parameter>
	<parameter type=”Expression”>
		<type>String</type>
		<formatString>ps –ef %1% | grep host %2%</formatString>
		<formatParmSpec> <!—0..N of these, 0 is fixed format string -->
			<type>EventType</type> <!—many of these types in the future -->
			<name>ev:msg</name>
		</formatParmSpec>
		<formatParmSpec> <!—0..N of these, 0 is fixed format string -->
			<type>EventType</type> <!—many of these types in the future -->
			<name>ev:host</name>
		</formatParmSpec>
	</parameter>
	<parameter type="Shell">/bin/sh -c</parameter>
	<parameter type="FieldName">ev:msg</parameter>
	<parameter type="FieldName">ev:msg2</parameter>
	<parameter type="FieldName">ev:msg3</parameter>
</filter>

 

Event Mapping

Resulting XML:

<event xmlns:ev="http://www.eventgnosis.com/">
	<ev:host>filipov</ev:host>
	<ev:app>ECS</ev:app>
	<ev:log>Application MS Log</ev:log>
	<ev:shellCommand.StartTime> Feb 25 2003 12:34:56 </ev:shellCommand.StartTime>
	<ev:shellCommand.EndTime> Feb 26 2003 23:10:05 </ev:shellCommand.EndTime>
	<ev:shellCommand.ExecutionSecs>13</ev:shellCommand.ExecutionSecs>
	<ev:shellCommand.CommandString>ps –ef | grep host hostJZ.txt</ev:shellCommand.CommandString>
	<ev:shellCommand.ProcessId>32786</ev:shellCommand.ProcessId>
	<ev:shellCommand.ErrorStatus>-32</ev:shellCommand.ErrorStatus>
	<ev:shellCommand.ExitCode>1</ev:shellCommand.ExitCode>
	<ev:protocol>Text Log</ev:protocol>
	<ev:msg1>hostJZ.txt.</ev:msg1>
	<ev:msg2>Not found.</ev:msg2>
	<ev:msg3>-1</ev:msg3>
</event>