« back to all changes in this revision
Viewing changes to sec.pl.man
- browse files at revision 3
- compare with another revision
- download diff
- download tarball
- view history from revision 3
- Committer: Bazaar Package Importer
- Author(s): Jaakko Niemi
- Date: 2005-02-28 21:36:41 UTC
- mfrom: (1.1.1 upstream)
- Revision ID: james.westby@ubuntu.com-20050228213641-b7718qmbi86z6ab5
Tags: 2.3.1-1
New upstream release
- files modified:
- ChangeLog
added
removed
sec.pl.man
1
1
.\"
2
.\" SEC version 2.2.4 - sec.man
2
.\" SEC version 2.3.1 - sec.man
3
3
.\" simple event correlation tool
4
4
.\"
5
.\" Copyright (C) 2000-2004 Risto Vaarandi
5
.\" Copyright (C) 2000-2005 Risto Vaarandi
6
6
.\"
7
7
.\" This program is free software; you can redistribute it and/or
8
8
.\" modify it under the terms of the GNU General Public License
18
18
.\" along with this program; if not, write to the Free Software
19
19
.\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
20
20
.\"
21
.TH sec 1 "June 2004" "SEC 2.2.4"
21
.TH sec 1 "February 2005" "SEC 2.3.1"
22
22
.SH NAME
23
23
sec \- simple event correlator
24
24
.SH SYNOPSIS
36
36
.br
37
37
[-poll_timeout=<poll timeout>]
38
38
.br
39
[-check_timeout=<check timeout>]
40
.br
39
41
[-blocksize=<io block size>]
40
42
.br
41
43
[-log=<logfile>]
78
80
.PP
79
81
After startup SEC reads lines from files, named pipes, or standard input,
80
82
matches the lines with regular expressions to recognize input events, and
81
correlates events according to the rules that are specified in its
82
configuration file(s). In order to detect a composite event, rules are used
83
sequentially in the same order as they are specified in the configuration
83
correlates events according to the rules in its configuration file(s).
84
In order to detect a composite event, rules are used
85
sequentially in the same order as they are given in the configuration
84
86
file. If there are two or more configuration files, rule sequences from
85
87
different files are used virtually in parallel.
86
88
SEC can be configured to produce its output by executing user-specified
95
97
composite events:
96
98
.PP
97
99
.B Single
98
- match input event and immediately execute an action that is
99
specified by rule.
100
- match input event and immediately execute an action.
100
101
.PP
101
102
.B SingleWithScript
102
103
- match input event and depending on the exit value of an external script,
110
111
.PP
111
112
.B Pair
112
113
- match input event, execute an action immediately, and ignore
113
following matching events until some other input event arrives. On
114
arrival of the second event execute another action.
114
following matching events until some other input event arrives.
115
On the arrival of the second event execute another action.
115
116
.PP
116
117
.B PairWithWindow
117
118
- match input event and wait for
118
119
.I t
119
120
seconds for other input event to arrive. If that event is not observed
120
within given time window, execute an action. If the event arrives on time,
121
within a given time window, execute an action. If the event arrives on time,
121
122
execute another action.
122
123
.PP
123
124
.B SingleWithThreshold
124
125
- count matching input events during
125
126
.I t
126
seconds and if given threshold is exceeded, execute an action and ignore
127
all matching events during rest of the time window.
127
seconds and if a given threshold is exceeded, execute an action and ignore
128
all matching events during the rest of the time window.
128
129
.PP
129
130
.B SingleWith2Thresholds
130
131
- count matching input events during
131
132
.I t1
132
seconds and if given threshold is exceeded, execute an action. Now start
133
to count matching events again and if their number per
133
seconds and if a given threshold is exceeded, execute an action. Then start
134
the counting of matching events again and if their number per
134
135
.I t2
135
seconds drops below second threshold, execute another action.
136
seconds drops below the second threshold, execute another action.
136
137
.PP
137
138
.B Suppress
138
- suppress matching input event (used to keep the
139
event from being matched by later rules)
139
- suppress matching input events (used to keep the events from being matched
140
by later rules).
140
141
.PP
141
142
.B Calendar
142
143
- execute an action at specific times.
143
144
.PP
144
If a rule defines a correlation of several events in a certain time window,
145
If a rule defines the correlation of several events in a certain time window,
145
146
the rule will start an event correlation operation when the first matching
146
147
event occurs. In order to distinguish between different event correlation
147
148
operations that have been started by the rules, every operation is assigned
166
167
.SH OPTIONS
167
168
.TP
168
169
.B "-conf=<file pattern>"
169
expand <file pattern> to filenames (using Perl
170
expand <file pattern> to filenames (with Perl
170
171
.BR glob ()
171
172
function) and read event correlation rules from every file. Multiple
172
173
.B -conf
173
174
options can be specified on commandline. Each time SEC receives a signal
174
175
that forces a configuration reload, <file pattern> is re-evaluated. See also
175
TIMING AND IPC section for a discussion about the processing order when
176
TIMING AND IPC section for a discussion about the rule processing order when
176
177
multiple configuration files are involved.
177
178
.TP
178
179
.B "-input=<file pattern>[=<context>]"
179
expand <file pattern> to filenames (using Perl
180
expand <file pattern> to filenames (with Perl
180
181
.BR glob ()
181
182
function) and use the files as event sources. An input file can be a regular
182
183
file, named pipe, or standard input if
191
192
<file pattern>. This will help the user to write rules that match data from
192
193
particular input source(s) only. When there is an
193
194
.B -input
194
option with <context> specified, this will automatically enable
195
option with <context> specified, it will automatically enable the
195
196
.B -intcontexts
196
197
option. See TIMING AND IPC section for more information.
197
198
.TP
211
212
after every <reopen_timeout> seconds until open succeeds.
212
213
.TP
213
214
.B "-poll_timeout=<poll_timeout>"
214
a positive real number that specifies how many seconds SEC will sleep
215
when no new data was read from input files. Default is 0.1 seconds.
215
a real number that specifies how many seconds SEC will sleep when no new data
216
were read from input files. Default is 0.1 seconds.
217
.TP
218
.B "-check_timeout=<check_timeout>"
219
if SEC has not observed new data in an input file, SEC will not poll the file
220
(both for status and data) during the next <check_timeout> seconds.
216
221
.TP
217
222
.B "-blocksize=<io_block_size>"
218
223
size of the block in bytes that SEC will attempt to read from input files
219
at once. Default is 1024 (i.e., read from an input file by 1KB blocks).
224
at once. Default is 1024 (i.e., read from input files by 1KB blocks).
220
225
.TP
221
226
.B "-log=<logfile>"
222
227
use <logfile> for logging SEC activities. Note that if the SEC standard error
223
228
is connected to a terminal, messages will be logged there, in order to
224
facilitate debugging. If
229
facilitate debugging. If the
225
230
.B -detach
226
231
option has also been specified, no logging to standard error will take
227
232
place.
232
237
.I local0
233
238
(see
234
239
.BR syslog (3)
235
for the possible facility values). Warning: be careful with this option if
240
for possible facility values). Warning: be careful with this option if
236
241
you use SEC for monitoring syslog logfiles, because it might cause message
237
242
loops when SEC log messages are written to SEC input files.
238
243
.TP
252
257
terminated with a non-zero exit code)
253
258
.br
254
259
4 - notification messages (normal system level events and interrupts, e.g.,
255
a reception of a signal)
260
the reception of a signal)
256
261
.br
257
262
5 - informative messages (information about external commands forked
258
263
from SEC)
262
267
Default <debuglevel> is 6 (i.e., log everything).
263
268
.TP
264
269
.B "-pid=<pidfile>"
265
use <pidfile> for storing the process ID of SEC. If this option is not given,
266
no pidfile will be created.
270
use <pidfile> for storing the process ID of SEC.
267
271
.TP
268
272
.B "-dump=<dumpfile>"
269
273
use <dumpfile> as the SEC dumpfile. Default is /tmp/sec.dump (see SIGNALS
276
280
.TP
277
281
.B "-bufsize=<input_buffer_size>"
278
282
set input buffer to hold last <input_buffer_size> lines that have been read
279
from input files. The content of input buffer will be compared with regular
280
expressions that are part of rule definitions (i.e., no more than
281
<input_buffer_size> lines can be matched by a regular expression at a time).
283
from input files. The content of input buffer will be compared with patterns
284
that are part of rule definitions (i.e., no more than <input_buffer_size>
285
lines can be matched by a pattern at a time).
282
286
Default size is 10 (i.e., 10 lines).
283
287
.TP
284
288
.B "-evstoresize=<event_store_size>"
292
296
.B "-quoting"
293
297
.TP
294
298
.B "-noquoting"
295
if
299
if the
296
300
.B -quoting
297
301
option is specified, event description strings that are supplied to
298
302
external shell commands of
299
303
.I shellcmd
300
304
and
301
305
.I spawn
302
actions will be put inside apostrophes. All
303
apostrophes ' that string originally contains will be replaced with
304
similarly looking backticks ` (since backticks will be surrounded by
305
apostrophes, they will lose their own special meaning). This option prevents
306
shell from interpreting special symbols that event description string might
307
contain. Default is
306
actions will be put inside apostrophes. All apostrophes ' that strings
307
originally contain will be masked. This option prevents the shell from
308
interpreting special symbols that event description strings might contain.
309
Default is
308
310
.BR -noquoting .
309
311
.TP
310
312
.B "-tail"
311
313
.TP
312
314
.B "-notail"
313
if
315
if the
314
316
.B -notail
315
option is specified, SEC will process all data that are
316
currently available in input files and exit when it reaches EOFs. Default is
317
option is specified, SEC will process all data that are currently available
318
in input files and exit after reaching all EOFs. Default is
317
319
.B -tail
318
320
- SEC will jump to the end of input files and wait for new lines to arrive.
319
With
321
With the
320
322
.B -tail
321
323
option, SEC follows an input file by its name (and not merely by its i-node).
322
324
If the input file is recreated or truncated, SEC will reopen it and process
323
325
its content from the start. If the input file is removed (i.e., there is
324
326
just an i-node left without name), SEC will keep the i-node open and wait for
325
the input file to be recreated. If
327
the input file to be recreated. If the
326
328
.B "-reopen_timeout=<reopen_timeout>"
327
option was specified and no data has been added to the i-node during
329
option was specified and no data have been added to the i-node during
328
330
<reopen_timeout> seconds, SEC will attempt to reopen the file without further
329
331
waiting for the file to be recreated.
330
332
.TP
331
333
.B "-fromstart"
332
334
.TP
333
335
.B "-nofromstart"
334
These flags have no meaning when
336
These flags have no meaning when the
335
337
.B -notail
336
338
option is also specified. When used in combination with
337
339
.B -tail
338
340
(or alone, since
339
341
.B -tail
340
is turned on by default),
342
is enabled by default),
341
343
.B -fromstart
342
344
will force SEC to read and process input files from the beginning to
343
345
the end, before the 'tail' mode is entered. Default is
346
348
.B "-detach"
347
349
.TP
348
350
.B "-nodetach"
349
if
351
if the
350
352
.B -detach
351
353
option is specified, SEC will disassociate itself from the controlling
352
354
terminal and become a daemon (note that SEC will close its standard input,
375
377
.B "-testonly"
376
378
.TP
377
379
.B "-notestonly"
378
if
380
if the
379
381
.B -testonly
380
382
option is specified, SEC will exit immediately after parsing the configuration
381
383
file(s). If the configuration file(s) contained no faulty rules, SEC will exit
401
403
on the next line. Lines which begin with #-symbol are treated as comments and
402
404
ignored (whitespace characters may precede #-symbol). Any comment line,
403
405
empty line, or end of the file will terminate the preceding rule definition.
404
.SS "SINGLE RULE"
405
The
406
.B Single
407
rule was designed for matching input events that require
408
immediate action to be taken. Its rule definition has the following
409
parameters:
410
.TP
411
.I "type"
412
fixed to Single (value is case insensitive, so single or sIngLe can be
413
used instead).
414
.TP
415
.I "continue (optional)"
416
TakeNext or DontCont (values are case insensitive). The first specifies that
417
search for matching rules will continue after the match (i.e., matching input
418
line(s) will be passed to the next rule), the second will quit the search.
419
If
420
.I continue
421
keyword is missing from the rule definition, DontCont is assumed.
422
.TP
423
.I "ptype"
424
RegExp[<number>], SubStr[<number>], NRegExp[<number>], or NSubStr[<number>]
425
(values are case insensitive). Specifies the type of the pattern
426
.I pattern
427
and how many input
428
lines the pattern was designed to match. If type begins with RegExp, pattern
429
is assumed to be a regular expression. If type begins with SubStr, pattern is
430
assumed to be a substring that will be searched in input line(s). NRegExp
431
and NSubStr are similar to RegExp and SubStr, except the result of the match
432
is negated. If <number> is given, pattern will be compared with last <number>
433
input lines. If <number> is omitted, 1 is assumed.
434
.TP
435
.I "pattern"
436
regular expression or substring that input line(s) will be compared with in
437
order to detect an event. If the regular expression matches the input line(s)
438
or the substring is found in the input line(s) (the original result of the
439
comparison will be negated for NRegExp and NSubStr), rule is considered
440
matching and action is executed. All regular expression constructs that Perl
441
allows are allowed here. For example, if case insensitive matching is desired
442
then (?i) can be prepended to the regular expression (see
406
.PP
407
Before describing each rule type in detail, patterns and pattern types,
408
context expressions, and action lists are discussed, since they are
409
important parts of the rule definition.
410
.SS "PATTERNS AND PATTERN TYPES"
411
SEC supports the following pattern types (if <number> is omitted, 1 is
412
assumed):
413
.TP
414
.I "SubStr[<number>]"
415
pattern is assumed to be a substring that will be searched in last <number>
416
input line(s). If the substring is found, the pattern matches.
417
The backslash constructs \\t, \\n, \\r, \\s, and \\0 can be used in the
418
pattern to denote tabulation, newline, carriage return, space character, and
419
empty string, while \\\\ denotes backslash itself. As an example, consider
420
the following pattern definition:
421
.sp
422
ptype=substr
423
.br
424
pattern=Backup done:\\tsuccess
425
.sp
426
The pattern matches lines containing "Backup done:<TAB>success".
427
.TP
428
.I "RegExp[<number>]"
429
pattern is assumed to be a regular expression that last <number> input
430
line(s) are compared with. If the pattern matches, backreference values will
431
be assigned to the special variables $1, $2, ..., and the matching input
432
line(s) will be assigned to the special variable $0. These special variables
433
can be used in some other parts of the rule definition.
434
All regular expression constructs that Perl allows are allowed in the
435
pattern (see
443
436
.BR perlre (1)
444
for more information).
445
If pattern is a substring then backslash constructs \\t, \\n, \\r, \\s,
446
and \\0 can be used to denote tabulation, newline, carriage return, space
447
character, and empty string, while \\\\ denotes backslash itself.
448
.TP
449
.I "context (optional)"
450
logical expression that consists of context names and Perl miniprograms
451
as operands; operands are combined with logical operators !, &&, ||, and
452
parentheses. If the operand begins with =, it is considered to be a Perl
453
miniprogram that will be executed by calling Perl
454
.BR eval ()
455
function; otherwise the operand is considered to be a context name.
456
.br
457
If the context name <context name> refers to an existing context, the value
458
of the operand <context name> is considered to be TRUE.
459
.br
460
If the Perl miniprogram <code> was successfully compiled and
461
.BR eval ()
462
returns TRUE for it in Perl scalar context, the value of
463
the operand <code> is considered to be TRUE. Note that since the Perl
464
miniprogram may contain operators that clash with the operators of the context
465
expression itself (e.g., '!'), it is strongly recommended to enclose the Perl
466
miniprogram in parentheses, e.g., consider the following context expression:
467
.br
468
context= =({my($temp) = 0; return !$temp;}) && !MYCONTEXT
469
.br
470
(also see VARIABLES AND EVAL section for more information).
471
.br
472
If the truth value of the logical expression is TRUE, then the rule matches;
473
otherwise the rule is considered not matching.
474
.br
475
If
476
.I pattern
477
was a regular expression with bracketing constructs, then
478
$1, $2, ... special variables can be used in context names to get the
479
backreference values, and special variable $0 can also be used to get the
480
input line(s) that were matched by
481
.IR pattern .
482
.br
483
If the logical expression is enclosed in square brackets [ ], e.g.,
484
.br
485
context=[MYCONTEXT1 && !MYCONTEXT2]
486
.br
487
it will
488
instruct SEC to evaluate the expression _before_ pattern matching operation,
489
i.e., before
490
.I pattern
491
is compared with input line(s) (the outermost set of brackets will be
492
removed by SEC during configuration file parsing). This could save CPU time
493
when many of the input lines are known to match
494
.I pattern
495
but not the logical expression.
496
.TP
497
.I "desc"
498
textual description of detected event. If
499
.I pattern
500
was a regular expression and bracketing constructs were used inside it, then
501
$1, $2, ... special variables can be used in event description to get the
502
backreference values, and special variable $0 can also be used to get the
503
input line(s) that were matched by
504
.IR pattern .
505
The event description formed here can be referenced by %s.
506
.TP
507
.I "action"
508
list of actions separated by semicolons that will be executed when event
509
is detected.
510
Action definition starts by keyword specifying the action type, followed by
511
additional parameters. If
512
.I pattern
513
was a regular expression and bracketing constructs were used inside it, then
514
$1, $2, ... special variables can be used in additional parameters to get the
515
backreference values, and special variable $0 can also be used to get the
516
input line(s) that were matched by
517
.IR pattern .
518
Also, the following variables can be used:
519
.br
520
%s - event description string
437
for more information). As an example, consider the following pattern
438
definition:
439
.sp
440
ptype=regexp
441
.br
442
pattern=(?i)(\\S+\\.mydomain).*printer: toner\\/ink low
443
.sp
444
The pattern matches "printer: toner/ink low" messages in a case insensitive
445
manner from printers belonging to .mydomain. Note that the printer hostname
446
is assigned to $1, while the whole message line is assigned to $0.
447
.TP
448
.I "PerlFunc[<number>]"
449
pattern is assumed to be a Perl function that last <number> input
450
line(s) are compared with. The Perl function is compiled at SEC startup by
451
calling Perl
452
.BR eval ()
453
function, and
454
.BR eval ()
455
must return a code reference for the pattern to be valid (also see VARIABLES
456
AND EVAL section for more information).
457
In order to check whether the pattern matches, SEC will call the function
458
in list context and pass last <number> input line(s) to the function as
459
parameters.
460
If the function returns several values or a single value that is TRUE in
461
boolean context, the pattern matches. If the pattern matches, return values
462
will be assigned to the special variables $1, $2, ..., and the matching input
463
line(s) will be assigned to the special variable $0. These special variables
464
can be used in some other parts of the rule definition. As an example,
465
consider the following pattern definition:
466
.sp
467
ptype=perlfunc2
468
.br
469
pattern=sub { return ($_[0] cmp $_[1]); }
470
.sp
471
The pattern compares two last input lines in a stringwise manner, and
472
matches if the lines are different. Note that the result of the comparison
473
is assigned to $1, while the two input lines are concatenated and assigned
474
to $0.
475
.TP
476
.I "NSubStr[<number>]"
477
like
478
.IR "SubStr[<number>]" ,
479
except the result of the match is negated.
480
.TP
481
.I "NRegExp[<number>]"
482
like
483
.IR "RegExp[<number>]" ,
484
except the result of the match is negated.
485
.TP
486
.I "NPerlFunc[<number>]"
487
like
488
.IR "PerlFunc[<number>]" ,
489
except the result of the match is negated.
490
.TP
491
.I "TValue"
492
pattern is assumed to be a truth value with TRUE and FALSE being legitimate
493
values for the pattern. TRUE always matches an input line while FALSE never
494
matches an input line.
495
.PP
496
Note that since Pair and PairWithWindow rules have two pattern definitions,
497
special variables $<number> set by the first pattern are shadowed when the
498
second pattern matches and sets the variables. In order to access the shadowed
499
variables, they must be referred to as %<number> (e.g., instead of $1 one has
500
to write %1). Also note that the second pattern of Pair and PairWithWindow
501
rules may contain $<number> variables, if the second pattern is of type
502
SubStr, NSubStr, Regexp, or NRegExp. The variables are substituted at
503
runtime with the values set by the first pattern.
504
.SS "CONTEXT EXPRESSIONS"
505
Context expression is a logical expression that consists of context names,
506
Perl miniprograms, and Perl functions as operands; operands are combined with
507
operators ! (logical NOT), && (logical AND), || (logical OR), and parentheses.
508
Context expressions are employed for activating or deactivating rules -
509
the truth value of the rule's context expression must be TRUE for the rule
510
to be applicable.
511
.PP
512
If the operand contains the arrow (->), the text following the arrow
513
is considered to be a Perl function that will be compiled at SEC startup by
514
calling Perl
515
.BR eval ()
516
function, and
517
.BR eval ()
518
must return a code reference for the operand to be valid (also
519
see VARIABLES AND EVAL section for more information).
520
If any text precedes the arrow, it is considered to be the list of parameters
521
for the function.
522
Parameters are separated by whitespace and may contain $<number> and
523
%<number> special variables. In order to evaluate the Perl function operand,
524
the function with its parameter list will be called in scalar context. If
525
the return value of the function is TRUE in boolean context, the truth value
526
of the operand is TRUE, otherwise its truth value is FALSE.
527
.PP
528
If the operand begins with the equal sign (=), the following text is
529
considered to be a Perl miniprogram. The miniprogram may contain $<number>
530
and %<number> special variables. In order to evaluate the Perl miniprogram
531
operand, it will be executed by calling Perl
532
.BR eval ()
533
function in scalar context (also see VARIABLES AND EVAL section for more
534
information). If the return value of the miniprogram is TRUE in boolean
535
context, the truth value of the operand is TRUE, otherwise its truth value
536
is FALSE.
537
.PP
538
Note that since Perl functions, miniprograms, and parameter lists may contain
539
strings that clash with the operators of the context expression (e.g., '!'),
540
it is strongly recommended to enclose them in parentheses, e.g.,
541
.PP
542
($1 $2) -> (sub { return ($_[0] != $_[1]); })
543
.PP
544
=({my($temp) = 0; return !$temp;})
545
.PP
546
If the operand is not a Perl function or program, it is considered to be
547
a context name. Context name may contain $<number> and %<number> special
548
variables. If the context name refers to an existing context, the truth
549
value of the operand is TRUE, otherwise its truth value is FALSE.
550
.PP
551
If the whole context expression is enclosed in square brackets [ ], e.g.,
552
.BR "[MYCONTEXT1 && !MYCONTEXT2]" ,
553
SEC evaluates the expression _before_ pattern matching operation (normally
554
the pattern is compared with input line(s) first, so that $<number> and
555
%<number> variables in the context expression could be replaced with their
556
values). Evaluating context expression first could save CPU time when many of
557
the input lines are known to match the pattern but not the context expression,
558
and the expression does not contain any variables.
559
.PP
560
As an example, consider the following context expressions:
561
.PP
562
-> ( sub { my(@stat) = stat("/var/log/messages"); \\
563
.br
564
return (!scalar(@stat) || time() - $stat[9] > 3600); } )
565
.PP
566
($1 $2) -> (sub { return ($_[0] != $_[1]); }) && C1
567
.PP
568
!(C1 || C2) && =("$1" eq "myhost.mydomain")
569
.PP
570
The first expression is TRUE when the /var/log/messages file does not exist
571
or was last modified more than 1 hour ago. The second expression is TRUE
572
when variables $1 and $2 are numerically not equal and the context
573
.B C1
574
exists.
575
The third expression is TRUE when contexts
576
.B C1
577
and
578
.B C2
579
do not exist and the $1 variable equals to the string "myhost.mydomain".
580
Note that the Perl code of the third expression is compiled each time the
581
expression is evaluated.
582
.SS "ACTION LISTS"
583
Action list consists of action definitions that are separated by semicolons.
584
Each action definition begins with a keyword specifying the action type,
585
followed by additional parameters. Additional parameters that do not have
586
a constant nature may contain $<number> and %<number> special variables.
587
Also, the following variables can be used in non-constant parameters:
588
.PP
589
%s - event description string (set either by the
590
.I desc
591
or
592
.I desc2
593
parameter of the rule definition).
521
594
.br
522
595
%t - textual timestamp (as returned by
523
596
.BR date (1)).
525
598
%u - numeric timestamp (as returned by
526
599
.BR time (2)).
527
600
.br
528
%<letter> - user-defined variables that can be set at SEC runtime with
601
%<alnum_name> - user-defined variables that can be set at SEC runtime with
529
602
certain actions like
530
603
.I assign
531
604
and
532
605
.I eval
533
(<letter> belongs to the set [A-Za-z], except the letters for
534
special variables described above).
535
.br
606
(<alnum_name> must begin with a letter and may contain letters, digits, and
607
underscores). In order to disambiguate <alnum_name> from the following text,
608
<alnum_name> must be enclosed in braces: %{<alnum_name>}.
609
.PP
610
In order to use semicolons inside a non-constant parameter, the parameter must
611
be enclosed in parentheses (the outermost set of parentheses will be removed
612
by SEC during configuration file parsing).
613
.PP
536
614
The following actions are supported:
537
.RS
538
.IP "none"
539
no action
540
.IP "logonly"
541
event description is logged
542
.IP "write <filename> [<event text>]"
543
Event <event text> and terminating newline are written to the file <filename>
544
(<filename> may not contain spaces). File may be a regular file, named pipe,
545
or standard output if
615
.TP
616
.I "none"
617
No action.
618
.TP
619
.I "logonly"
620
Event description (the value of the %s variable) is logged.
621
.TP
622
.I "write <filename> [<event text>]"
623
Event string <event text> and terminating newline are written to the file
624
<filename> (<filename> may not contain spaces). File may be a regular file,
625
named pipe, or standard output if
546
626
.B -
547
627
was specified.
548
628
If the file is a regular file, <event text> is appended to the end of the file.
549
629
If the file does not exist, it is created as a regular file before writing.
550
%-variables can be used in <filename> and <event text>. If <event text> is
551
omitted, %s is assumed for its value (i.e., event description string is
552
written to the file). Though
630
If <event text> is omitted, %s is assumed for its value. Though
553
631
.I write
554
can also be expressed through
632
can also be expressed through the
555
633
.I shellcmd
556
634
action,
557
635
.I write
559
637
.BR fork (2)
560
638
like
561
639
.I shellcmd
562
does. In order to use semicolons inside the <filename> or <event text>
563
parameter, the parameter must be enclosed in parentheses (the outermost set
564
of parentheses will be removed by SEC during configuration file parsing).
565
.IP "shellcmd <shellcmd>"
566
shell command <shellcmd> is executed. %-variables can be used in <shellcmd>.
567
If
640
does.
641
.TP
642
.I "shellcmd <shellcmd>"
643
Shell command <shellcmd> is executed. If the
568
644
.B -quoting
569
645
option was specified, %s will be converted to '%s' before supplying it to
570
shell command (see
646
shell command (see the
571
647
.B -quoting
572
648
and
573
649
.B -noquoting
574
options). In order to use semicolons inside the <shellcmd>
575
parameter, the parameter must be enclosed in parentheses (the outermost set
576
of parentheses will be removed by SEC during configuration file parsing).
577
.IP "spawn <shellcmd>"
578
identical to
650
options).
651
.TP
652
.I "spawn <shellcmd>"
653
Identical to the
579
654
.I shellcmd
580
action, except the following: every line from the standard output of
655
action, except the following - every line from the standard output of
581
656
<shellcmd> is treated like SEC input line and matched against the rules.
582
657
This is done by applying
583
658
.I "event 0 <line>"
584
to every line from standard output (see
659
to every line from standard output (see the
585
660
.I event
586
661
action). Note that if <shellcmd> outputs a large data set at once, SEC
587
662
will process it all at once, so if <shellcmd> enters an endless "busy write"
588
663
loop, it will block SEC from doing anything other than processing its output.
589
In order to use semicolons inside the <shellcmd> parameter,
590
the parameter must be enclosed in parentheses (the outermost set of
591
parentheses will be removed by SEC during configuration file parsing).
592
.IP "pipe '<event text>' [<shellcmd>]"
593
Event <event text> is fed to the standard input of shell command <shellcmd>
594
(apostrophes are used to mark the beginning and end of the event text, in
595
order to distinguish it from <shellcmd>). %-variables can be used in
596
<event text> and <shellcmd>.
664
.TP
665
.I "pipe '<event text>' [<shellcmd>]"
666
Event string <event text> and terminating newline are fed to the standard
667
input of shell command <shellcmd> (apostrophes are used to mark the beginning
668
and end of <event text>, in order to distinguish it from <shellcmd>).
597
669
If <event text> is omitted and there is nothing between apostrophes, %s is
598
assumed for <event text> (i.e., event description string is fed to <shellcmd>).
599
If <shellcmd> is omitted, <event text> is written to standard output.
600
In order to use semicolons inside the <event text> or <shellcmd>
601
parameter, the parameter must be enclosed in parentheses (the outermost set
602
of parentheses will be removed by SEC during configuration file parsing).
603
.IP "create [<name> [<time> [<action list>] ] ]
604
context with the name <name>, with the lifetime of <time> seconds, and with
605
empty event store is created (<name> may not contain spaces).
606
%-variables can be used in context name <name>.
607
If <name> is omitted, %s is assumed for its value
608
(i.e., context with the name of event description is created).
670
assumed for <event text>. If <shellcmd> is omitted, <event text> is written
671
to standard output.
672
.TP
673
.I "create [<name> [<time> [<action list>] ] ]
674
Context with the name <name>, with the lifetime of <time> seconds, and with
675
empty event store is created (<name> may not contain spaces, and <time> is
676
an integer constant). If <name> is omitted, %s is assumed for its value.
609
677
Specifying 0 as <time> or omitting the value means infinite lifetime.
610
678
If <action list> is specified, it will be executed when context's lifetime is
611
679
exceeded. If <action list> is made up of more than one action, semicolons
612
680
must be used to separate the actions, and the list must be enclosed in
613
parentheses. In order to use semicolons inside the <name> parameter,
614
the parameter must be enclosed in parentheses (the outermost set of
615
parentheses will be removed by SEC during configuration file parsing).
616
If already existing context is recreated with
681
parentheses. If already existing context is recreated with
617
682
.IR create ,
618
683
its lifetime will be extended for <time> seconds and its event store will
619
684
be emptied.
620
.IP "delete [<name>]"
621
context with the name <name> is deleted (<name> may not contain spaces).
622
%-variables can be used in context name <name>.
623
If <name> is omitted, %s is assumed for its value
624
(i.e., context with the name of event description is deleted).
685
.TP
686
.I "delete [<name>]"
687
Context with the name <name> is deleted (<name> may not contain spaces).
688
If <name> is omitted, %s is assumed for its value.
625
689
If non-existing context is deleted, no operation will be performed.
626
In order to use semicolons inside the <name> parameter,
627
the parameter must be enclosed in parentheses (the outermost set of
628
parentheses will be removed by SEC during configuration file parsing).
629
.IP "set <name> <time> [<action list>]
630
settings for the context with the name <name> will be changed (<name> may
631
not contain spaces). New lifetime of the context will be <time> seconds with
632
optional <action list> to be executed when the lifetime is exceeded. Event
633
store of the context will not be changed by
690
.TP
691
.I "obsolete [<name>]"
692
Behaves like
693
.IR delete ,
694
except the action list of the context <name> (if the context has an action
695
list) will be executed before deletion.
696
.TP
697
.I "set <name> <time> [<action list>]
698
Settings for the context with the name <name> will be changed (<name> may
699
not contain spaces, and <time> is an integer constant). New lifetime of the
700
context will be <time> seconds with optional <action list> to be executed
701
when the lifetime is exceeded. Event store of the context will not be changed
702
by
634
703
.IR set .
635
%-variables can be used in context name <name>.
636
704
Specifying 0 as <time> means infinite lifetime.
637
705
If <action list> is made up of more than one action, semicolons must be
638
706
used to separate the actions, and the list must be enclosed in parentheses.
639
In order to use semicolons inside the <name> parameter, the parameter must
640
be enclosed in parentheses (the outermost set of parentheses will be removed
641
by SEC during configuration file parsing).
642
.IP "alias <name> [<alias>]"
643
An alias name <alias> will be created for the context with the name <name>.
707
.TP
708
.I "alias <name> [<alias>]"
709
An alias name <alias> will be created for the context with the name <name>
710
(<name> and <alias> may not contain spaces).
644
711
After the name <alias> has been created for a context, the context can be
645
referred to by using both <alias> and <name>. %-variables can be used in
646
<name> and <alias>. If <alias> is omitted, %s is assumed for its value. If
647
context with the name <name> does not exist, or the name <alias> already
712
referred to by using both <alias> and <name>. If <alias> is omitted, %s is
713
assumed for its value.
714
If context with the name <name> does not exist, or the name <alias> already
648
715
exists, the alias will not be created. Internally, SEC does not distinguish
649
716
in any way between <alias> and <name> - they are both pointers to the same
650
context data structure. This means that all SEC configuration file directives
651
that are valid for <name> are also valid for <alias>. Note that since <alias>
652
and <name> are pointers to the same context, it makes no difference whether
717
context data structure. Therefore, it makes no difference whether
653
718
context attributes (like lifetime, event store, etc.) are changed by calling
654
719
an action (e.g.,
655
720
.I set
662
727
destroyed, and all context names (which are now pointers to unallocated
663
728
memory) are removed from the list of context names. Also note that if the
664
729
lifetime of the context is exceeded, its action list is executed only once,
665
no matter how many names the context has. In order to use semicolons inside
666
the <name> or <alias> parameter, the parameter must be enclosed in parentheses
667
(the outermost set of parentheses will be removed by SEC during configuration
668
file parsing).
669
.IP "unalias [<alias>]"
670
context name <alias> is removed from the list of context names, so that the
730
no matter how many names the context has.
731
.TP
732
.I "unalias [<alias>]"
733
Context name <alias> is removed from the list of context names, so that the
671
734
name <alias> can no longer be used to refer to the context it was previously
672
735
associated with (<alias> may not contain spaces).
673
%-variables can be used in context name <alias>. If <name> is omitted, %s is
674
assumed for its value. If
736
If <alias> is omitted, %s is assumed for its value. If
675
737
.I unalias
676
738
is called for non-existing context name, no operation will be performed.
677
739
If the name <alias> was the last reference to a context, the
680
742
.I delete
681
743
and the context will be deleted; otherwise the context will continue to
682
744
exist under another name(s) with its event store and other attributes intact.
683
In order to use semicolons inside the <alias> parameter,
684
the parameter must be enclosed in parentheses (the outermost set of
685
parentheses will be removed by SEC during configuration file parsing).
686
.IP "add <name> [<event text>]"
687
Event <event text> is added to the event store of the context <name>
745
.TP
746
.I "add <name> [<event text>]"
747
Event string <event text> is added to the event store of the context <name>
688
748
(<name> may not contain spaces). Events in the store are ordered by the
689
749
time they were added, and every
690
750
.I add
691
adds event to the end of the store. %-variables can be used in <name> and
692
<event text>. If <event text>
693
is omitted, %s is assumed for its value (i.e., event description string is
694
added to event store). If context <name> does not exist, the context will
695
be created with infinite lifetime, empty action list and empty event store
696
(as with
751
adds event to the end of the store. If <event text> is omitted, %s is assumed
752
for its value. If context <name> does not exist, the context will be created
753
with infinite lifetime, empty action list and empty event store (as with
697
754
.IR "create <name>" )
698
before adding the event. In order to use semicolons inside
699
the <name> or <event text> parameter, the parameter must be enclosed
700
in parentheses (the outermost set of parentheses will be removed by SEC
701
during configuration file parsing).
702
.IP "fill <name> [<event text>]"
755
before adding the event. If <event text> contains newlines, it will be split
756
into parts by using the newline symbol as a delimiter, and each part is
757
added to the event store as a separate event string.
758
.TP
759
.I "fill <name> [<event text>]"
703
760
Behaves like
704
761
.IR add ,
705
762
except the event store of the context <name> will be emptied before
706
763
<event text> is added.
707
.IP "report <name> [<shellcmd>]"
764
.TP
765
.I "report <name> [<shellcmd>]"
708
766
Event store of the context <name> is reported with shell command <shellcmd>
709
767
(<name> may not contain spaces). Reporting means that events from the store
710
768
are fed to standard input of <shellcmd> in the order they were added into the
711
store, every event on a separate line. %-variables can be used in
712
<name> and <shellcmd>. If <shellcmd> is omitted, events from the store
713
are written to standard output. In order to use semicolons inside
714
the <name> or <shellcmd> parameter, the parameter must be enclosed
715
in parentheses (the outermost set of parentheses will be removed by SEC
716
during configuration file parsing).
717
.IP "copy <name> %<letter>"
769
store, every event on a separate line. If <shellcmd> is omitted, events from
770
the store are written to standard output.
771
.TP
772
.I "copy <name> %<alnum_name>"
718
773
Event store of the context <name> is assigned to a user-defined variable
719
%<letter>. Before assignment takes place, lines from the event store
720
are joined into a scalar by using the newline character as the separator
721
(as with Perl join("\\n", @array)). %-variables can be used in <name>.
722
In order to use semicolons inside the <name> parameter, the parameter must
723
be enclosed in parentheses (the outermost set of parentheses will be removed
724
by SEC during configuration file parsing).
725
.IP "empty <name> [%<letter>]"
774
%<alnum_name> (<name> may not contain spaces). Before assignment takes
775
place, lines from the event store are joined into a scalar by using the
776
newline character as the separator (as with Perl join("\\n", @array)).
777
.TP
778
.I "empty <name> [%<alnum_name>]"
726
779
Behaves like
727
780
.IR copy ,
728
781
except the event store of the context <name> will be emptied after it
729
has been assigned to the variable %<letter>. If %<letter> is omitted,
782
has been assigned to the variable %<alnum_name>. If %<alnum_name> is omitted,
730
783
.I empty
731
784
simply removes all lines from the event store.
732
.IP "event [<time>] [<event text>]"
733
after <time> seconds a synthetic event <event text> is created. SEC treats
734
the <event text> string exactly like line(s) read from input - it is inserted
735
into the input buffer in order to compare it with rules. %-variables can be
736
used in <event text>. If <event text> is omitted, %s is assumed for its value
737
(i.e., event description string is inserted into the input buffer).
785
.TP
786
.I "event [<time>] [<event text>]"
787
After <time> seconds a synthetic event <event text> is created (<time> is an
788
integer constant). SEC treats the <event text> string exactly like line(s)
789
read from input - it is inserted into the input buffer in order to compare it
790
with rules. If <event text> is omitted, %s is assumed for its value.
738
791
Specifying 0 as <time> or omitting the value means now. If <event text>
739
contains newlines, it will be split into parts by using the newline symbol as
740
a delimiter, and each part is submitted with
741
.I event
742
action separately. In order to use semicolons inside the <event text>
743
parameter, the parameter must be enclosed in parentheses (the outermost set
744
of parentheses will be removed by SEC during configuration file parsing).
745
.IP "reset [<rule_number>] [<event text>]"
746
cancel event correlation operations that are currently detecting the
747
composite event <event text>, i.e., SEC will terminate event correlation
748
operations that have <event text> in their keys as event description string
749
(if such operations exist, see RULES AND EVENT CORRELATION OPERATIONS section
750
for more information). If there are multiple configuration files specified,
792
contains newlines, it will be split into parts by using the newline symbol as
793
a delimiter, and each part is created as a separate synthetic event.
794
.TP
795
.I "reset [<rule_number>] [<event text>]"
796
Cancel event correlation operations that are currently detecting the
797
composite event <event text> (<rule_number> is a string constant), i.e.,
798
SEC will terminate event correlation operations that have <event text> in
799
their keys as event description string (if such operations exist, see
800
RULES AND EVENT CORRELATION OPERATIONS section for more information).
801
If there are multiple configuration files specified,
751
802
.I reset
752
803
can cancel only those correlation operations that have been started by the
753
804
rules from the same configuration file where the
754
805
.I reset
755
806
action itself is defined.
756
%-variables can be used in <event text>.
757
If <event text> is omitted, %s is assumed for its value (i.e.,
758
correlation operation that is detecting the composite event equal to event
759
description string is cancelled).
807
If <event text> is omitted, %s is assumed for its value.
760
808
Since correlation operations started by different rules may detect composite
761
809
events that have identical description strings, rule number can be optionally
762
810
specified to point to a correlation operation that was started by a specific
763
811
rule (1 means first rule in the configuration file, 2 means second, etc.;
764
812
0 denotes the current rule).
765
813
If + or - is prepended to <rule_number>, it is considered to be an offset
766
from current rule (for example, -1 means previous rule and +1 next rule).
814
from current rule (e.g., -1 means previous rule and +1 next rule).
767
815
For example, if a rule definition with the
768
816
.I reset
769
817
action is given in the configuration file named my.conf, then
774
822
.I "reset Counting linkdown events"
775
823
will terminate event correlation operations with keys "my.conf | X | Counting
776
824
linkdown events", where X runs from 0 to N-1 and N is the number of rules in
777
the configuration file my.conf. If there is no operation with a given key,
825
the configuration file my.conf. If no operation with a given key exists,
778
826
.I reset
779
827
will take no action.
780
In order to use semicolons inside the <event text> parameter,
781
the parameter must be enclosed in parentheses (the outermost set of
782
parentheses will be removed by SEC during configuration file parsing).
783
.IP "assign %<letter> [<text>]"
784
Text <text> is assigned to a user-defined variable %<letter>. %-variables
785
(including %<letter> itself) can be used in <text>. If <text> is omitted,
786
%s is assumed for its value. In order to use semicolons inside
787
the <text> parameter, the parameter must be enclosed in parentheses (the
788
outermost set of parentheses will be removed by SEC during configuration
789
file parsing).
790
.IP "eval %<letter> <code>"
828
.TP
829
.I "assign %<alnum_name> [<text>]"
830
Text <text> is assigned to a user-defined variable %<alnum_name>. If <text>
831
is omitted, %s is assumed for its value.
832
.TP
833
.I "eval %<alnum_name> <code>"
791
834
The parameter <code> is assumed to be a Perl miniprogram that will be executed
792
835
by calling Perl
793
836
.BR eval ()
794
function for it and storing the return value(s) to an internal array (this
795
allows the miniprogram to return both scalar and list values).
796
The array elements are joined into a scalar by using the newline character as
797
the separator (as with Perl join("\\n", @array)), and the scalar is assigned
798
to the variable %<letter>. If
837
function in list context. If the miniprogram returns a single value, it will
838
be assigned to the variable %<alnum_name>. If the miniprogram returns several
839
values, they will be joined into a scalar by using the newline character as
840
a separator (as with Perl join("\\n", @array)), and the scalar will be
841
assigned to the variable %<alnum_name>. If no value is returned or
799
842
.BR eval ()
800
fails, nothing is assigned to the variable %<letter>.
801
%-variables (including %<letter> itself) can be used in <code>. Note that
802
before calling
843
fails, no assignment will take place.
844
Note that before calling
803
845
.BR eval (),
804
%-variables are replaced with their values and therefore can't be used as
805
lvalues. Since most Perl programs contain semicolons which are also used
806
by SEC as separators between actions, it is recommended to enclose
846
$<number>, %<number>, and %<alnum_name> variables in the miniprogram are
847
replaced with their values and therefore can't be used as lvalues.
848
Since most Perl programs contain semicolons which are also
849
used by SEC as separators between actions, it is recommended to enclose
807
850
the <code> parameter in parentheses, in order to avoid the inperpretation
808
of semicolons inside the code by SEC (the outermost set of parentheses
809
will be removed by SEC during configuration file parsing). Also see
810
VARIABLES AND EVAL section for more information.
811
.RE
812
.PP
851
of semicolons inside the code by SEC. Also see VARIABLES AND EVAL section for
852
more information.
853
.TP
854
.I "call %<alnum_name1> %<alnum_name2> [<parameter list>]"
855
The parameter %<alnum_name2> is assumed to be a reference to a Perl function
856
that was created previously with the
857
.I eval
858
action. The function will be called in list context by passing optional
859
parameter list to the function (parameters are separated by whitespace).
860
If the function returns a single value, it will
861
be assigned to the variable %<alnum_name1>. If the function returns several
862
values, they will be joined into a scalar by using the newline character as
863
a separator (as with Perl join("\\n", @array)), and the scalar will be
864
assigned to the variable %<alnum_name1>. If no value is returned or
865
%<alnum_name2> is not a code reference, no assignment will take place.
866
Also see VARIABLES AND EVAL section for more information.
867
.PP
868
.B Examples:
869
.PP
870
spawn /bin/tail -f /var/log/trapd.log
871
.PP
872
Follow the /var/log/trapd.log file and feed to SEC input all lines that are
873
appended to the file.
874
.PP
875
pipe '%t: $0' /bin/mail -s "alert message" root@localhost
876
.PP
877
Mail the timestamp and the value of the $0 variable to the local root.
878
.PP
879
add ftp_$1 $0; set ftp_$1 1800 (report ftp_$1 /bin/mail root@localhost)
880
.PP
881
Add the value of the $0 variable to the event store of the context
882
.BR "ftp_<the value of $1>" .
883
Also extend the context's lifetime for 30 minutes, so that when the context's
884
lifetime is exceeded, its event store will be mailed to the local root.
885
.PP
886
eval %funcptr ( sub { my(@buf) = split(/\\n/, $_[0]); \\
887
.br
888
my(@ret) = grep(!/^#/, @buf); return @ret; } ); \\
889
.br
890
copy C1 %in; call %out %funcptr %in; fill C1 %out
891
.PP
892
Create a subroutine for weeding out comment lines from the input list, and
893
use this subroutine for removing comment lines from the event store of the
894
context
895
.BR C1 .
896
.SS "OTHER ISSUES"
813
897
As already noted, SEC context expressions and action lists may contain
814
898
parentheses which are used for grouping and masking purposes. When SEC parses
815
899
its configuration, it checks whether parentheses in context expressions and
829
913
by SEC during configuration file parsing), e.g.,
830
914
.PP
831
915
action=eval %o (print "\\)";)
916
.SS "SINGLE RULE"
917
The
918
.B Single
919
rule was designed for matching input events that require
920
immediate action to be taken. Its rule definition has the following
921
parameters:
922
.TP
923
.I "type"
924
fixed to Single (value is case insensitive, so single or sIngLe can be
925
used instead).
926
.TP
927
.I "continue (optional)"
928
TakeNext or DontCont (values are case insensitive). The first specifies that
929
search for matching rules will continue after the match (i.e., input line(s)
930
that match
931
.I pattern
932
and
933
.I context
934
will be passed to the next rule), the second will quit the search.
935
If
936
.I continue
937
keyword is missing from the rule definition, DontCont is assumed.
938
.TP
939
.I "ptype"
940
pattern type (value is case insensitive).
941
.TP
942
.I "pattern"
943
pattern.
944
.TP
945
.I "context (optional)"
946
context expression.
947
.TP
948
.I "desc"
949
textual description of detected event.
950
.TP
951
.I "action"
952
action list that will be executed when event is detected.
953
.PP
954
Note that
955
.IR context ,
956
.IR desc ,
957
and
958
.I action
959
parameters may contain $<number> variables.
832
960
.PP
833
961
.B Examples:
834
962
.PP
906
1034
TakeNext or DontCont (values are case insensitive).
907
1035
.TP
908
1036
.I "ptype"
909
RegExp[<number>], SubStr[<number>], NRegExp[<number>], or NSubStr[<number>]
910
(values are case insensitive).
1037
pattern type (value is case insensitive).
911
1038
.TP
912
1039
.I "pattern"
913
regular expression or substring that input line(s) will be compared with in
914
order to detect an event.
1040
pattern.
915
1041
.TP
916
1042
.I "context (optional)"
917
context definition. If
918
.I pattern
919
was a regular expression then $0, $1, $2, ... special variables can be used
920
in this field.
1043
context expression.
921
1044
.TP
922
1045
.I "script"
923
1046
script that is executed after
924
1047
.I pattern
925
has matched some input line(s). The names of all existing contexts are fed
1048
and
1049
.I context
1050
have matched some input line(s). The names of all existing contexts are fed
926
1051
to the standard input of the script, a name per line.
927
1052
If the script returns zero for its exit value,
928
1053
.I action
929
1054
will be executed; if the script returns non-zero,
930
1055
.I action2
931
will be executed (if given). If
932
.I pattern
933
was a regular expression then $0, $1, $2, ... special variables can be used
934
in this field.
1056
will be executed (if given).
935
1057
.TP
936
1058
.I "desc"
937
textual description of detected event. If
938
.I pattern
939
was a regular expression then $0, $1, $2, ... special variables can be used
940
in this field. The event description formed here can be referenced by %s.
1059
textual description of detected event.
941
1060
.TP
942
1061
.I "action"
943
1062
action list that will be executed when
944
.I pattern
945
has matched some input line(s) and
946
1063
.I script
947
returns zero for its exit value. If
948
.I pattern
949
was a regular expression then $0, $1, $2, ... special variables can be used
950
in this field.
1064
returns zero for its exit value.
951
1065
.TP
952
1066
.I "action2 (optional)"
953
1067
action list that will be executed when
954
.I pattern
955
has matched some input line(s) and
956
1068
.I script
957
returns non-zero for its exit value. If
958
.I pattern
959
was a regular expression then $0, $1, $2, ... special variables can be used
960
in this field.
961
.PP
962
Note that since the runtime of the script that is specified by the
1069
returns non-zero for its exit value.
1070
.PP
1071
Note that
1072
.IR context ,
1073
.IR script ,
1074
.IR desc ,
1075
.IR action ,
1076
and
1077
.I action2
1078
parameters may contain $<number> variables.
1079
.PP
1080
Also note that since the runtime of the script that is specified by the
963
1081
.I script
964
1082
parameter is not limited in any way, waiting for that script
965
1083
to complete could freeze the entire event processing for an indefinite
966
1084
amount of time. Therefore, once the
967
1085
.I pattern
968
parameter has matched input line(s), SEC does not wait for the script to
1086
and
1087
.I context
1088
parameters have matched input line(s), SEC does not wait for the script to
969
1089
complete but rather continues its work. The exit value of the script
970
1090
will be fetched when the script actually terminates, and depending on
971
1091
the exit value, either
998
1118
/usr/local/scripts/notify.sh "Interface <ipaddress> down"
999
1119
.PP
1000
1120
(note also that SEC feeds the names of all existing contexts to the
1001
standard input of /usr/local/scripts/ping.sh script.)
1121
standard input of the /usr/local/scripts/ping.sh script.)
1002
1122
.SS "SINGLEWITHSUPPRESS RULE"
1003
1123
The
1004
1124
.B SingleWithSuppress
1005
rule was designed to implement event correlation
1125
rule was designed to implement the event correlation
1006
1126
operation called
1007
1127
.IR compression ,
1008
where multiple instances of the same event are reduced into single event.
1128
where multiple instances of event A are reduced into single event.
1009
1129
Its rule definition is similar to the Single rule, except of additional
1010
1130
.I window
1011
1131
parameter:
1017
1137
TakeNext or DontCont (values are case insensitive).
1018
1138
.TP
1019
1139
.I "ptype"
1020
RegExp[<number>], SubStr[<number>], NRegExp[<number>], or NSubStr[<number>]
1021
(values are case insensitive).
1140
pattern type (value is case insensitive).
1022
1141
.TP
1023
1142
.I "pattern"
1024
regular expression or substring that input line(s) will be compared with in
1025
order to detect event A.
1143
pattern for detecting event A.
1026
1144
.TP
1027
1145
.I "context (optional)"
1028
context definition. If
1029
.I pattern
1030
was a regular expression then $0, $1, $2, ... special variables can be used
1031
in this field.
1146
context expression.
1032
1147
.TP
1033
1148
.I "desc"
1034
textual description of event A. If
1035
.I pattern
1036
was a regular expression then $0, $1, $2, ... special variables can be used
1037
in this field. The event description formed here can be referenced by %s.
1149
textual description of event A.
1038
1150
.TP
1039
1151
.I "action"
1040
1152
action list that will be executed when event A is first observed. Following
1041
instances of event A will be ignored. If
1042
.I pattern
1043
was a regular expression then $0, $1, $2, ... special variables can be used
1044
in this field.
1153
instances of event A will be ignored.
1045
1154
.TP
1046
1155
.I "window"
1047
1156
time in seconds that following events A are ignored for.
1048
1157
.PP
1158
Note that
1159
.IR context ,
1160
.IR desc ,
1161
and
1162
.I action
1163
parameters may contain $<number> variables.
1164
.PP
1049
1165
.B Examples:
1050
1166
.PP
1051
1167
type=SingleWithSuppress
1078
1194
.SS "PAIR RULE"
1079
1195
The
1080
1196
.B Pair
1081
rule was designed to implement one of the basic forms of
1197
rule was designed to implement one of the basic forms of the
1082
1198
.I temporal relationship
1083
event correlation operation, where 2 or more
1084
events are reduced into event pair inside given time window.
1199
event correlation operation, where two or more events A and B are reduced
1200
into event pair (A, B) inside a given time window.
1085
1201
Its rule definition has the following parameters:
1086
1202
.TP
1087
1203
.I "type"
1091
1207
TakeNext or DontCont (values are case insensitive). Specifies if
1092
1208
input line(s) that match
1093
1209
.I pattern
1210
and
1211
.I context
1094
1212
will be passed to the next rule.
1095
1213
.TP
1096
1214
.I "ptype"
1097
RegExp[<number>], SubStr[<number>], NRegExp[<number>], or NSubStr[<number>]
1098
(values are case insensitive).
1215
pattern type (value is case insensitive).
1099
1216
.TP
1100
1217
.I "pattern"
1101
regular expression or substring that input line(s) will be compared with in
1102
order to detect event A.
1218
pattern for detecting event A.
1103
1219
.TP
1104
1220
.I "context (optional)"
1105
context definition. If
1106
.I pattern
1107
was a regular expression then $0, $1, $2, ... special variables can be used
1108
in this field.
1221
context expression.
1109
1222
.TP
1110
1223
.I "desc"
1111
textual description of event A. If
1112
.I pattern
1113
was a regular expression then $0, $1, $2, ... special variables can be used
1114
in this field. The event description formed here can be referenced by %s.
1224
textual description of event A.
1115
1225
.TP
1116
1226
.I "action"
1117
1227
action list that will be executed when event A is first observed. Following
1118
instances of event A will be ignored. If
1119
.I pattern
1120
was a regular expression then $0, $1, $2, ... special variables can be used
1121
in this field.
1228
instances of event A will be ignored.
1122
1229
.TP
1123
1230
.I "continue2 (optional)"
1124
1231
TakeNext or DontCont (values are case insensitive). Specifies if
1125
1232
input line(s) that match
1126
1233
.I pattern2
1234
and
1235
.I context2
1127
1236
will be passed to the next rule.
1128
1237
.TP
1129
1238
.I "ptype2"
1130
RegExp[<number>], SubStr[<number>], NRegExp[<number>], or NSubStr[<number>]
1131
(values are case insensitive).
1239
pattern type (value is case insensitive).
1132
1240
.TP
1133
1241
.I "pattern2"
1134
regular expression or substring that input line(s) will be compared with in
1135
order to detect event B. If
1136
.I pattern
1137
was a regular expression then $0, $1, $2, ... special variables can be used
1138
in this field.
1242
pattern for detecting event B.
1139
1243
.TP
1140
1244
.I "context2 (optional)"
1141
context definition. If
1142
.I pattern
1143
or
1144
.I pattern2
1145
parameter was a regular expression, then $0, $1, $2, ... special variables
1146
can be used in this field. If
1147
.I pattern2
1148
was a regular expression, then values of
1149
.I pattern2
1150
are used, otherwise values of
1151
.I pattern
1152
are used.
1153
.br
1154
In the special case where both
1155
.I pattern
1156
and
1157
.I pattern2
1158
were regular expressions, %0, %1, %2, ... special variables can be used to
1159
retrieve values of
1160
.IR pattern ,
1161
while $0, $1, $2, ... refer to values of
1162
.IR pattern2 .
1245
context expression.
1163
1246
.TP
1164
1247
.I "desc2"
1165
textual description of event B. If
1166
.I pattern
1167
or
1168
.I pattern2
1169
parameter was a regular expression, then $0, $1, $2, ... special variables
1170
can be used in this field. If
1171
.I pattern2
1172
was a regular expression, then values of
1173
.I pattern2
1174
are used, otherwise values of
1175
.I pattern
1176
are used.
1177
.br
1178
In the special case where both
1179
.I pattern
1180
and
1181
.I pattern2
1182
were regular expressions, %0, %1, %2, ... special variables can be used to
1183
retrieve values of
1184
.IR pattern ,
1185
while $0, $1, $2, ... refer to values of
1186
.IR pattern2 .
1187
The event description formed here can be referenced by %s.
1248
textual description of event B.
1188
1249
.TP
1189
1250
.I "action2"
1190
action list that will be executed when event B is observed. If
1191
.I pattern
1192
or
1193
.I pattern2
1194
parameter was a regular expression, then $0, $1, $2, ... special variables
1195
can be used in this field. If
1196
.I pattern2
1197
was a regular expression, then values of
1198
.I pattern2
1199
are used, otherwise values of
1200
.I pattern
1201
are used.
1202
.br
1203
In the special case where both
1204
.I pattern
1205
and
1206
.I pattern2
1207
were regular expressions, %0, %1, %2, ... special variables can be used to
1208
retrieve values of
1209
.IR pattern ,
1210
while $0, $1, $2, ... refer to values of
1211
.IR pattern2 .
1251
action list that will be executed when event B is observed. After executing
1252
.I action2
1253
the event correlation operation terminates.
1212
1254
.TP
1213
1255
.I "window (optional)"
1214
1256
time
1224
1266
to infinity (i.e., if event B does not appear,
1225
1267
event A will be ignored forever).
1226
1268
.PP
1269
Note that
1270
.IR context ,
1271
.IR desc ,
1272
.IR action ,
1273
.IR context2 ,
1274
.IR desc2 ,
1275
and
1276
.I action2
1277
parameters may contain $<number> variables. The
1278
.I pattern2
1279
parameter may contain $<number> variables if
1280
.I ptype2
1281
supports variable substitutions at runtime. If
1282
.I pattern2
1283
shadows the $<number> variables of
1284
.IR pattern ,
1285
then
1286
.IR context2 ,
1287
.IR desc2 ,
1288
and
1289
.I action2
1290
parameters may contain %<number> variables.
1291
.PP
1227
1292
.B Examples:
1228
1293
.PP
1229
1294
type=Pair
1262
1327
.SS "PAIRWITHWINDOW RULE"
1263
1328
The
1264
1329
.B PairWithWindow
1265
rule was designed to implement another variant of
1330
rule was designed to implement another variant of the
1266
1331
.I temporal relationship
1267
event correlation operation that checks if
1268
event A will be followed by event B inside given time window.
1332
event correlation operation that checks if event A will be followed by
1333
event B inside a given time window.
1269
1334
Its rule definition has the following parameters:
1270
1335
.TP
1271
1336
.I "type"
1275
1340
TakeNext or DontCont (values are case insensitive). Specifies if input
1276
1341
line(s) that match
1277
1342
.I pattern
1343
and
1344
.I context
1278
1345
will be passed to the next rule.
1279
1346
.TP
1280
1347
.I "ptype"
1281
RegExp[<number>], SubStr[<number>], NRegExp[<number>], or NSubStr[<number>]
1282
(values are case insensitive).
1348
pattern type (value is case insensitive).
1283
1349
.TP
1284
1350
.I "pattern"
1285
regular expression or substring that input line(s) will be compared with in
1286
order to detect event A.
1351
pattern for detecting event A.
1287
1352
.TP
1288
1353
.I "context (optional)"
1289
context definition. If
1290
.I pattern
1291
was a regular expression then $0, $1, $2, ... special variables can be used
1292
in this field.
1354
context expression.
1293
1355
.TP
1294
1356
.I "desc"
1295
textual description of event A. If
1296
.I pattern
1297
was a regular expression then $0, $1, $2, ... special variables can be used
1298
in this field. The event description formed here can be referenced by %s.
1357
textual description of event A.
1299
1358
.TP
1300
1359
.I "action"
1301
1360
action list that is executed after event A was observed and event B did not
1302
appear within given time window. If
1303
.I pattern
1304
was a regular expression then $0, $1, $2, ... special variables can be used
1305
in this field.
1361
appear within the given time window.
1306
1362
.TP
1307
1363
.I "continue2 (optional)"
1308
1364
TakeNext or DontCont (values are case insensitive). Specifies if input
1309
1365
line(s) that match
1310
1366
.I pattern2
1367
and
1368
.I context2
1311
1369
will be passed to the next rule.
1312
1370
.TP
1313
1371
.I "ptype2"
1314
RegExp[<number>], SubStr[<number>], NRegExp[<number>], or NSubStr[<number>]
1315
(values are case insensitive).
1372
pattern type (value is case insensitive).
1316
1373
.TP
1317
1374
.I "pattern2"
1318
regular expression or substring that input line(s) will be compared with in
1319
order to detect event B. If
1320
.I pattern
1321
was a regular expression then $0, $1, $2, ... special variables can be used
1322
in this field.
1375
pattern for detecting event B.
1323
1376
.TP
1324
1377
.I "context2 (optional)"
1325
context definition. If
1326
.I pattern
1327
or
1328
.I pattern2
1329
parameter was a regular expression, then $0, $1, $2, ... special variables
1330
can be used in this field. If
1331
.I pattern2
1332
was a regular expression, then values of
1333
.I pattern2
1334
are used, otherwise values of
1335
.I pattern
1336
are used.
1337
.br
1338
In the special case where both
1339
.I pattern
1340
and
1341
.I pattern2
1342
were regular expressions, %0, %1, %2, ... special variables can be used to
1343
retrieve values of
1344
.IR pattern ,
1345
while $0, $1, $2, ... refer to values of
1346
.IR pattern2 .
1347
The event description formed here can be referenced by %s.
1378
context expression.
1348
1379
.TP
1349
1380
.I "desc2"
1350
textual description of event B. If
1351
.I pattern
1352
or
1353
.I pattern2
1354
parameter was a regular expression, then $0, $1, $2, ... special variables
1355
can be used in this field. If
1356
.I pattern2
1357
was a regular expression, then values of
1358
.I pattern2
1359
are used, otherwise values of
1360
.I pattern
1361
are used.
1362
.br
1363
In the special case where both
1364
.I pattern
1365
and
1366
.I pattern2
1367
were regular expressions, %0, %1, %2, ... special variables can be used to
1368
retrieve values of
1369
.IR pattern ,
1370
while $0, $1, $2, ... refer to values of
1371
.IR pattern2 .
1372
The event description formed here can be referenced by %s.
1381
textual description of event B.
1373
1382
.TP
1374
1383
.I "action2"
1375
1384
action list that is executed after event A was observed and event B appeared
1376
within given time window. If
1377
.I pattern
1378
or
1379
.I pattern2
1380
parameter was a regular expression, then $0, $1, $2, ... special variables
1381
can be used in this field. If
1382
.I pattern2
1383
was a regular expression, then values of
1384
.I pattern2
1385
are used, otherwise values of
1386
.I pattern
1387
are used.
1388
.br
1389
In the special case where both
1390
.I pattern
1391
and
1392
.I pattern2
1393
were regular expressions, %0, %1, %2, ... special variables can be used to
1394
retrieve values of
1395
.IR pattern ,
1396
while $0, $1, $2, ... refer to values of
1397
.IR pattern2 .
1385
within the given time window. After executing
1386
.I action2
1387
the event correlation operation terminates.
1398
1388
.TP
1399
1389
.I "window"
1400
1390
size of the time window in seconds.
1401
1391
.PP
1392
Note that
1393
.IR context ,
1394
.IR desc ,
1395
.IR action ,
1396
.IR context2 ,
1397
.IR desc2 ,
1398
and
1399
.I action2
1400
parameters may contain $<number> variables. The
1401
.I pattern2
1402
parameter may contain $<number> variables if
1403
.I ptype2
1404
supports variable substitutions at runtime. If
1405
.I pattern2
1406
shadows the $<number> variables of
1407
.IR pattern ,
1408
then
1409
.IR context2 ,
1410
.IR desc2 ,
1411
and
1412
.I action2
1413
parameters may contain %<number> variables.
1414
.PP
1402
1415
.B Examples:
1403
1416
.PP
1404
1417
type=PairWithWindow
1434
1447
.SS SINGLEWITHTHRESHOLD RULE
1435
1448
The
1436
1449
.B SingleWithThreshold
1437
rule was designed to implement
1450
rule was designed to implement the
1438
1451
.I counting
1439
event correlation operation, where event instances are counted inside
1440
given time window and the number of events is compared with a threshold
1441
value. Its rule definition has the following parameters:
1452
event correlation operation, where instances of event A are counted inside
1453
a given time window and the number of events is compared with a threshold
1454
value, in order to detect a composite event B.
1455
Its rule definition has the following parameters:
1442
1456
.TP
1443
1457
.I "type"
1444
1458
fixed to SingleWithThreshold (value is case insensitive).
1447
1461
TakeNext or DontCont (values are case insensitive).
1448
1462
.TP
1449
1463
.I "ptype"
1450
RegExp[<number>], SubStr[<number>], NRegExp[<number>], or NSubStr[<number>]
1451
(values are case insensitive).
1464
pattern type (value is case insensitive).
1452
1465
.TP
1453
1466
.I "pattern"
1454
regular expression or substring that input line(s) will be compared with in
1455
order to detect event A.
1467
pattern for detecting event A.
1456
1468
.TP
1457
1469
.I "context (optional)"
1458
context definition. If
1459
.I pattern
1460
was a regular expression then $0, $1, $2, ... special variables can be used
1461
in this field.
1470
context expression.
1462
1471
.TP
1463
1472
.I "desc"
1464
textual description of event. If
1465
.I pattern
1466
was a regular expression then $0, $1, $2, ... special variables can be used
1467
in this field. The event description formed here can be referenced by %s.
1473
textual description of event B.
1468
1474
.TP
1469
1475
.I "action"
1470
1476
action list that is executed when
1471
1477
.I thresh
1472
instances of event A have been observed within given time window. After that
1473
all events A will be ignored during rest of the time window. If
1474
.I pattern
1475
was a regular expression then $0, $1, $2, ... special variables can be used
1476
in this field.
1478
instances of event A have been observed within the given time window. After
1479
that all events A will be ignored during the rest of the time window.
1477
1480
.TP
1478
1481
.I "window"
1479
1482
size of the time window in seconds. The window is sliding - if event A has
1480
1483
been observed less than
1481
1484
.I thresh
1482
1485
times at the end of the window, the beginning of the window is moved to the
1483
moment of 2nd appearance of event A, and the counting operation will continue.
1484
If there is no 2nd instance of event A (i.e., event has been observed only
1486
occurrence time of the second instance of event A, and the counting operation
1487
will continue.
1488
If there is no second instance of event A (i.e., event has been observed only
1485
1489
once), the correlation operation will terminate.
1486
1490
.TP
1487
1491
.I "thresh"
1488
1492
threshold value.
1489
1493
.PP
1494
Note that
1495
.IR context ,
1496
.IR desc ,
1497
and
1498
.I action
1499
parameters may contain $<number> variables.
1500
.PP
1490
1501
.B Examples:
1491
1502
.PP
1492
1503
type=SingleWithThreshold
1519
1530
action=shellcmd notify.sh "%s"; reset 0 %s
1520
1531
.PP
1521
1532
the correlation operation will terminate itself after calling notify.sh, and
1522
next matching line will always start a new counting operation.
1533
the next matching line will always start a new counting operation.
1523
1534
.SS "SINGLEWITH2THRESHOLDS RULE"
1524
1535
The
1525
1536
.B SingleWith2Thresholds
1526
1537
rule was designed to implement another variant
1527
of
1538
of the
1528
1539
.I counting
1529
event correlation operation, where event instances are
1530
counted twice - first for checking if the threshold value is exceeded, and
1531
then for checking if the number of events will stay below the second
1532
threshold value. Its rule definition has the following parameters:
1540
event correlation operation, where instances of event A are counted twice -
1541
first for checking if the threshold value is exceeded (in order to detect
1542
a composite event B), and then for checking if the number of instances will
1543
stay below the second threshold value (in order to detect a composite event C).
1544
Its rule definition has the following parameters:
1533
1545
.TP
1534
1546
.I "type"
1535
1547
fixed to SingleWith2Thresholds (value is case insensitive).
1538
1550
TakeNext or DontCont (values are case insensitive).
1539
1551
.TP
1540
1552
.I "ptype"
1541
RegExp[<number>], SubStr[<number>], NRegExp[<number>], or NSubStr[<number>]
1542
(values are case insensitive).
1553
pattern type (value is case insensitive).
1543
1554
.TP
1544
1555
.I "pattern"
1545
regular expression or substring that input line(s) will be compared with in
1546
order to detect event A.
1556
pattern for detecting event A.
1547
1557
.TP
1548
1558
.I "context (optional)"
1549
context definition. If
1550
.I pattern
1551
was a regular expression then $0, $1, $2, ... special variables can be used
1552
in this field.
1559
context expression.
1553
1560
.TP
1554
1561
.I "desc"
1555
textual description of event. If
1556
.I pattern
1557
was a regular expression then $0, $1, $2, ... special variables can be used
1558
in this field. The event description formed here can be referenced by %s.
1562
textual description of event B.
1559
1563
.TP
1560
1564
.I "action"
1561
1565
action list that is executed when
1566
1570
.I thresh2
1567
1571
and time window
1568
1572
.IR window2 .
1569
If
1570
.I pattern
1571
was a regular expression then $0, $1, $2, ... special variables can be used
1572
in this field.
1573
1573
.TP
1574
1574
.I "window"
1575
size of the first time window in seconds. The window is sliding - if event A
1576
has been observed less than
1577
.I thresh
1578
times at the end of the window, the beginning of the window is moved to the
1579
moment of 2nd appearance of event A, and the counting operation will continue.
1580
If there is no 2nd instance of event A (i.e., event has been observed only
1581
once), the correlation operation will terminate.
1575
size of the first time window in seconds. The window is sliding.
1582
1576
.TP
1583
1577
.I "thresh"
1584
1578
first threshold value.
1585
1579
.TP
1586
1580
.I "desc2"
1587
textual description of event. If
1588
.I pattern
1589
was a regular expression then $0, $1, $2, ... special variables can be used
1590
in this field. The event description formed here can be referenced by %s.
1581
textual description of event C.
1591
1582
.TP
1592
1583
.I "action2"
1593
1584
action list that is executed if no more than
1594
1585
.I thresh2
1595
events A were observed within last
1586
instances of event A have been observed within last
1596
1587
.I window2
1597
seconds.
1598
If
1599
.I pattern
1600
was a regular expression then $0, $1, $2, ... special variables can be used
1601
in this field.
1588
seconds. After executing
1589
.I action2
1590
the event correlation operation terminates.
1602
1591
.TP
1603
1592
.I "window2"
1604
1593
size of the second time window in seconds. The window is sliding.
1605
1594
.TP
1606
1595
.I "thresh2"
1607
second threshold value. If
1608
.I pattern
1609
was a regular expression then $0, $1, $2, ... special variables can be used
1610
in this field.
1596
second threshold value.
1597
.PP
1598
Note that
1599
.IR context ,
1600
.IR desc ,
1601
.IR action ,
1602
.IR desc2 ,
1603
and
1604
.I action2
1605
parameters may contain $<number> variables.
1611
1606
.PP
1612
1607
.B Examples:
1613
1608
.PP
1651
1646
.I event suppression
1652
1647
and
1653
1648
.IR filtering ,
1654
where event is suppressed or filtered out if certain context is present or
1649
where event A is suppressed or filtered out if certain context is present or
1655
1650
if the event parameters match the pattern specified. Its rule definition has
1656
1651
the following parameters:
1657
1652
.TP
1659
1654
fixed to Suppress (value is case insensitive).
1660
1655
.TP
1661
1656
.I "ptype"
1662
RegExp[<number>], SubStr[<number>], NRegExp[<number>], or NSubStr[<number>]
1663
(values are case insensitive).
1657
pattern type (value is case insensitive).
1664
1658
.TP
1665
1659
.I "pattern"
1666
regular expression or substring that input line(s) will be compared with in
1667
order to detect event A (or its subclass) that must be suppressed (or
1660
pattern for detecting event A (or its subclass) that must be suppressed (or
1668
1661
filtered out).
1669
1662
.TP
1670
1663
.I "context (optional)"
1671
context definition. If
1672
.I pattern
1673
was a regular expression then $0, $1, $2, ... special variables can be used
1674
in this field.
1664
context expression.
1675
1665
.TP
1676
1666
.I "desc (optional)"
1677
1667
textual description of this rule.
1678
1668
.PP
1669
Note that the
1670
.I context
1671
parameter may contain $<number> variables.
1672
.PP
1679
1673
.B Examples:
1680
1674
.PP
1681
1675
type=Suppress
1711
1705
.BR crontab (1)
1712
1706
for more information). Time specification consists of five fields separated
1713
1707
by whitespace characters. First field denotes minutes (allowed values 0-59),
1714
second field hours (0-23), third field days (allowed values 0-31, 0 denotes
1715
last day of the month), fourth field months (allowed values 1-12), and fifth
1716
field weekdays (allowed values 0-7, 0 and 7 denotes Sunday). Asterisks (*),
1717
ranges of numbers (e.g., 8-11), and lists (2,5-6,9) are allowed as field
1718
values.
1708
second field hours (allowed values 0-23), third field days (allowed values
1709
0-31, 0 denotes the last day of the month), fourth field months (allowed
1710
values 1-12), and fifth field weekdays (allowed values 0-7, 0 and 7 denote
1711
Sunday). Asterisks (*), ranges of numbers (e.g., 8-11), and lists (e.g.,
1712
2,5,7-9) are allowed as field values.
1719
1713
.TP
1720
1714
.I "context (optional)"
1721
context definition.
1715
context expression.
1722
1716
.TP
1723
1717
.I "desc"
1724
event description string (can be referenced by %s).
1718
event description string.
1725
1719
.TP
1726
1720
.I "action"
1727
1721
action list to be executed.
1811
1805
their design allows them to complete their work almost immediately without
1812
1806
starting an event correlation operation). Therefore, the
1813
1807
.I desc
1814
parameter of these rules does not influence the scope and the number of event
1808
parameter of these rules does not influence the number and the scope of event
1815
1809
correlation operations.
1816
1810
.SH TIMING AND IPC
1817
1811
There are several kinds of events that SEC reacts to - changes in input
1818
files (e.g., appearance of new data), reception of a signal, status change
1812
files (e.g., appearance of new data), the reception of a signal, status change
1819
1813
of a child process, and time related events (expiration of the context
1820
1814
lifetime, a Calendar rule that has become active, etc.).
1821
1815
.PP
1822
1816
When new data appear in SEC input files, only one line will be read at a time
1823
1817
(even when more lines are available), after which the input buffer is updated
1824
1818
with the line that was read. Input buffer contains the last N lines from
1825
the SEC input, in the order they were read (the value of N can be set by the
1819
the SEC input, in the order they were read (the value of N can be set with the
1826
1820
.B -bufsize
1827
parameter). Updating means that the last element (the oldest line) is removed
1828
from the end of the input buffer, while the new line becomes the first element
1829
of the buffer. Note that when synthetic events have been created with
1830
.I event
1831
action(s) and new input data is also available in input files, events created
1832
with
1833
.I event
1834
action(s) are always read first by SEC. After no more such events are
1821
option). Updating the input buffer means that the last element (the oldest
1822
line) is removed from the end of the buffer, while the new line becomes the
1823
first element of the buffer. Note that when synthetic events have been created
1824
with the
1825
.I event
1826
action and new input data is also available in input files, synthetic events
1827
are always read first by SEC. After no more such events are
1835
1828
available for reading, SEC will read new data from input files.
1836
1829
.PP
1837
1830
After the buffer has been updated (every update always adds only one
1838
1831
and removes only one line), the rules from configuration files are
1839
1832
processed, comparing the rules against the new content of the input buffer.
1840
1833
Even when a rule matches and its action list specifies an immediate change
1841
in the buffer (e.g., by using
1834
in the buffer (e.g., by using the
1842
1835
.I event
1843
1836
action), the input buffer will _not_ be updated until all the rules have
1844
1837
been compared against the current content of the buffer.
1870
1863
.PP
1871
1864
After the input buffer has been updated and its content has been processed
1872
1865
by the rules, SEC handles the signals that have been received since the last
1873
check, and also reads possible output from its child processes (if there are
1874
any child processes).
1866
check, and also reads possible output from its child processes.
1875
1867
.PP
1876
When the timeout specified by the
1868
When the timeout specified with the
1877
1869
.B -cleantime
1878
parameter has expired, SEC also checks the contexts and the event correlation
1870
option has expired, SEC also checks the contexts and the event correlation
1879
1871
operations that have timers associated with them (e.g., SingleWithSuppress
1880
1872
and PairWithWindow rules). This means that the value of
1881
1873
.B -cleantime
1882
1874
should be relatively small, in order to keep the event correlation
1883
1875
operations accurate. By setting the
1884
1876
.B -cleantime
1885
parameter to 0, SEC will check the event correlation timers after reading
1877
option value to 0, SEC will check the event correlation timers after reading
1886
1878
every line, but this will consume more CPU time. The higher the value, the
1887
less CPU time will be consumed, so the value of
1879
less CPU time will be consumed, so the value of the
1888
1880
.B -cleantime
1889
depends on your requirements. Note that if the
1881
option depends on your requirements. Note that if the
1890
1882
.B -poll_timeout
1891
value exceeds the value given with
1883
option value exceeds the value given with
1892
1884
.BR -cleantime ,
1893
1885
the
1894
1886
.B -poll_timeout
1895
value takes precedence (i.e., sleeps after unsuccessful polls will not be
1896
shortened).
1887
option value takes precedence (i.e., sleeps after unsuccessful polls will
1888
not be shortened).
1897
1889
.PP
1898
If
1890
If the
1899
1891
.B -intevents
1900
1892
commandline option is given, SEC will generate internal events when
1901
1893
it is started up, when it receives certain signals, and when it terminates
1907
1899
when SEC starts up). The following internal events are
1908
1900
supported:
1909
1901
.PP
1910
SEC_STARTUP - generated when SEC is started (once
1902
SEC_STARTUP - generated when SEC is started (once the
1911
1903
.B -intevents
1912
option is given, this event will always be the first event that SEC
1904
option has been given, this event will always be the first event that SEC
1913
1905
observes)
1914
1906
.PP
1915
1907
SEC_RESTART - generated after SEC has received
1924
1916
.PP
1925
1917
SEC_SHUTDOWN - generated when SEC receives
1926
1918
.B SIGTERM
1927
signal, or when SEC reaches EOFs of input files after being started with
1919
signal, or when SEC reaches all EOFs of input files after being started with
1920
the
1928
1921
.B -notail
1929
1922
option. After generating SEC_SHUTDOWN event, SEC will sleep for 3 seconds
1930
1923
before sending SIGTERM to its child processes (if there are any child
1937
1930
The SEC_INTERNAL_EVENT context will be deleted immediately after the
1938
1931
internal event has been processed by all rules.
1939
1932
.PP
1940
If
1933
If the
1941
1934
.B -intcontexts
1942
1935
commandline option is given, or there is an
1943
1936
.B -input
1959
1952
.PP
1960
1953
type=Suppress
1961
1954
.br
1962
ptype=RegExp
1963
.br
1964
pattern=.*
1965
.br
1966
context=!_FILE_EVENT_/dev/logpipe
1955
ptype=TValue
1956
.br
1957
pattern=TRUE
1958
.br
1959
context=[!_FILE_EVENT_/dev/logpipe]
1967
1960
.PP
1968
1961
will pass to the following rules only those lines that were read from
1969
1962
/dev/logpipe.
1974
1967
.IR pipe ,
1975
1968
and
1976
1969
.IR report
1977
actions involve creating a child process. The communication between SEC and
1978
its child processes takes place through pipes (created with Perl pipe opens
1979
like open(FH, "| mycommand"), or
1970
actions involve the creation of a child process. The communication between
1971
SEC and its child processes takes place through pipes (created with Perl pipe
1972
opens like open(FH, "| mycommand") or
1980
1973
.BR pipe (2)
1981
1974
system call). Note that the running time of children is not limited in any
1982
1975
way, so long-running processes can be started from SEC. For instance, you
2006
1999
it takes more time from the shell to process and start cmd1 than cmd2).
2007
2000
.SH VARIABLES AND EVAL
2008
2001
There are two kinds of variables that can be used in SEC rule definitions -
2009
$<number> and %<number> variables that hold regular expression backreference
2010
values, and %<letter> variables (like %s, %t, and %u) that have been designed
2011
for use in action lists. Backreference variables will always be evaluated
2012
first, and the evaluation takes place right after the corresponding regular
2013
expression has matched the input event.
2014
All the $<number> and %<number> variables will be replaced with the
2015
backreference values at once, even when they are part of the action list
2016
definition and this action list is going to be executed at a later time.
2017
%<letter> variables, in turn, will be evaluated right before the action list
2018
is actually executed. Note that %<letter> variables are currently limited to
2019
have names of 1 character from the set A-Za-z (i.e., the Latin alphabet).
2020
If a variable does not have a value (e.g., $4 when there are just two
2021
backreference values), it will be left intact, i.e., it is not replaced with
2022
an empty string.
2002
$<number> and %<number> variables that are set during pattern matching,
2003
and %<alnum_name> variables (like %s, %t, and %u) that have been designed
2004
for use in action lists.
2005
All $<number> and %<number> variables will be substituted with their values
2006
immediately after input line(s) have matched the rule, even when they are
2007
part of the action list definition and this action list is going to be
2008
executed at a later time.
2009
%<alnum_name> variables, in turn, will be substituted with their values right
2010
before the action list is actually executed.
2011
If a variable does not have a value (e.g., $4 when the pattern returned just
2012
two values), it will be left intact, i.e., it is not replaced with an empty
2013
string.
2023
2014
.PP
2024
2015
In order to mask the variables, an extra $ or % must be prepended to them,
2025
e.g., $$1 evaluates to $1, and not a dollar sign followed by the first
2026
backreference value. Also, all occurrences of $$ will be converted to $
2027
when $<number> variables are evaluated, and all occurrences of %% will be
2028
converted to % when %<number> or %<letter> variables are evaluated,
2016
e.g., $$1 yields $1, and not a dollar sign followed by the first value
2017
returned by the pattern. Also, all occurrences of $$ will be converted to $
2018
when $<number> variables are substituted, and all occurrences of %% will be
2019
converted to % when %<number> or %<alnum_name> variables are substituted,
2029
2020
so that one could use $ or % together with variable names (e.g., $$$1 will
2030
yield a dollar sign that is followed by the first backreference value).
2031
Please note the following caveat for the Pair* rules which employ
2032
a regular expression for their second pattern: since both %<number> and
2033
%<letter> variables may be used in the second action list, and %<number>
2034
variables are evaluated first (at the moment when the first pattern matches
2035
input line(s) and an event correlation operation is started), all occurrences
2036
of %% in the second action list have been already replaced with a single
2037
percent sign by the time when %<letter> variables are finally evaluated.
2021
yield a dollar sign that is followed by the first value returned by
2022
the pattern).
2023
.PP
2024
Please note the following caveat for Pair and PairWithWindow rules when
2025
the second pattern shadows the $<number> variables of the first pattern -
2026
since both %<number> and %<alnum_name> variables may be used in the second
2027
action list and %<number> variables are substituted first (at the moment
2028
when the first pattern matches input line(s) and the event correlation
2029
operation is started), all occurrences of %% in the second action list have
2030
already been replaced with a single percent sign by the time when
2031
%<alnum_name> variables are finally substituted.
2038
2032
(E.g., in order to express %%t in the second action list, one must actually
2039
2033
write it as %%%%t or %%%t, since after %% to % conversion they both yield
2040
2034
%%t.)
2041
2035
.PP
2042
SEC allows the user to define context expressions and actions which involve
2043
calls to Perl
2036
SEC allows the user to define patterns, context expressions, and actions
2037
which involve calls to Perl
2044
2038
.BR eval ()
2045
function. By using
2046
.BR eval (),
2047
the user can execute arbitrary Perl programs. Furthermore, in addition
2048
to explicitly using %<letter> variables that are global across the rules,
2049
the user can implicitly employ Perl global variables created by
2039
function. In addition to explicitly using %<alnum_name> variables that are
2040
global across the rules, the user can implicitly employ Perl variables created
2041
with
2050
2042
.BR eval ()
2051
2043
for the same purpose. E.g., when SEC has executed the following action
2052
2044
.PP
2053
2045
action=eval %a ($b = 1)
2054
2046
.PP
2055
the variable $b and its value will become visible for the subsequent calls to
2056
.BR eval (),
2057
and with the following context expression
2047
the variable $b and its value will become visible in the following context
2048
expression
2058
2049
.PP
2059
2050
context= =(++$b > 10)
2060
2051
.PP
2061
one can, for instance, implement event counting implicitly.
2052
(with that expression one can implement event counting implicitly).
2062
2053
In order to avoid possible clashes with the variables inside the SEC
2063
2054
code itself, all calls for
2064
2055
.BR eval ()
2065
2056
are made in the main::SEC namespace (i.e., inside the special package
2066
2057
main::SEC).
2067
2058
This still leaves the user with an opportunity to set the variables within
2068
the SEC code (e.g., by using the main:: prefix), and thus alter the behavior
2059
the SEC code (e.g., by using the main:: prefix), and thus to alter the behavior
2069
2060
of SEC, but this is only recommended for advanced users who have studied the
2070
2061
code thoroughly and know what they are doing.
2071
2062
.SH EXAMPLES
2493
2484
SEC will terminate gracefully (all SEC child processes will receive
2494
2485
.BR SIGTERM ).
2495
2486
.SH AUTHOR
2496
Risto Vaarandi <risto.vaarandi@eyp.ee>
2487
Risto Vaarandi (ristov at users d0t s0urcef0rge d0t net)
2497
2488
.SH "SEE ALSO"
2498
2489
.BR crontab (1),
2499
2490
.BR date (1),
Loggerhead is a web-based interface for Breezy
Version: 2.0.1