-
Notifications
You must be signed in to change notification settings - Fork 1
/
man.html
9311 lines (6973 loc) · 252 KB
/
man.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML><HEAD><TITLE>Man page of sec</TITLE>
</HEAD><BODY>
<H1>sec</H1>
Section: User Commands (1)<BR>Updated: November 2024<BR>
<HR>
<A NAME="index"> </A><H2>Index</H2>
<DL>
<DT><A HREF="#lbAB">NAME</A><DD>
<DT><A HREF="#lbAC">SYNOPSIS</A><DD>
<DT><A HREF="#lbAD">DESCRIPTION</A><DD>
<DT><A HREF="#lbAE">OPTIONS</A><DD>
<DT><A HREF="#lbAF">CONFIGURATION FILES</A><DD>
<DT><A HREF="#lbAG">PATTERNS, PATTERN TYPES AND MATCH VARIABLES</A><DD>
<DT><A HREF="#lbAH">CONTEXTS AND CONTEXT EXPRESSIONS</A><DD>
<DT><A HREF="#lbAI">ACTIONS, ACTION LISTS AND ACTION LIST VARIABLES</A><DD>
<DT><A HREF="#lbAJ">PARSING ISSUES</A><DD>
<DT><A HREF="#lbAK">RULE TYPES</A><DD>
<DL>
<DT><A HREF="#lbAL">SINGLE RULE</A><DD>
<DT><A HREF="#lbAM">SINGLEWITHSCRIPT RULE</A><DD>
<DT><A HREF="#lbAN">SINGLEWITHSUPPRESS RULE</A><DD>
<DT><A HREF="#lbAO">PAIR RULE</A><DD>
<DT><A HREF="#lbAP">PAIRWITHWINDOW RULE</A><DD>
<DT><A HREF="#lbAQ">SINGLEWITHTHRESHOLD RULE</A><DD>
<DT><A HREF="#lbAR">SINGLEWITH2THRESHOLDS RULE</A><DD>
<DT><A HREF="#lbAS">EVENTGROUP RULE</A><DD>
<DT><A HREF="#lbAT">SUPPRESS RULE</A><DD>
<DT><A HREF="#lbAU">CALENDAR RULE</A><DD>
<DT><A HREF="#lbAV">JUMP RULE</A><DD>
<DT><A HREF="#lbAW">OPTIONS RULE</A><DD>
</DL>
<DT><A HREF="#lbAX">EVENT CORRELATION OPERATIONS</A><DD>
<DT><A HREF="#lbAY">INPUT PROCESSING AND TIMING</A><DD>
<DT><A HREF="#lbAZ">INTERNAL EVENTS AND CONTEXTS</A><DD>
<DT><A HREF="#lbBA">CHILD PROCESSES</A><DD>
<DT><A HREF="#lbBB">PERL INTEGRATION</A><DD>
<DT><A HREF="#lbBC">EXAMPLES</A><DD>
<DL>
<DT><A HREF="#lbBD">Example 1 - a ruleset for Cisco events</A><DD>
<DT><A HREF="#lbBE">Example 2 - hierarchically organized rulesets for iptables and sshd events</A><DD>
</DL>
<DT><A HREF="#lbBF">ENVIRONMENT</A><DD>
<DT><A HREF="#lbBG">SIGNALS</A><DD>
<DT><A HREF="#lbBH">BUGS</A><DD>
<DT><A HREF="#lbBI">AUTHOR</A><DD>
<DT><A HREF="#lbBJ">ACKNOWLEDGMENTS</A><DD>
<DT><A HREF="#lbBK">SEE ALSO</A><DD>
</DL>
<HR>
<A NAME="lbAB"> </A>
<H2>NAME</H2>
sec - simple event correlator
<A NAME="lbAC"> </A>
<H2>SYNOPSIS</H2>
<DL COMPACT>
<DT><B>sec</B>
<DD>
[--conf=<file pattern> ...]
<BR>
[--input=<file pattern>[=<context>] ...]
<BR>
[--input-timeout=<input timeout>]
<BR>
[--timeout-script=<timeout script>]
<BR>
[--reopen-timeout=<reopen timeout>]
<BR>
[--check-timeout=<check timeout>]
<BR>
[--poll-timeout=<poll timeout>]
<BR>
[--socket-timeout=<socket timeout>]
<BR>
[--blocksize=<io block size>]
<BR>
[--bufsize=<input buffer size>]
<BR>
[--evstoresize=<event store size>]
<BR>
[--cleantime=<clean time>]
<BR>
[--log=<logfile>]
<BR>
[--syslog=<facility>]
<BR>
[--debug=<debuglevel>]
<BR>
[--pid=<pidfile>]
<BR>
[--dump=<dumpfile>]
<BR>
[--user=<username>]
<BR>
[--group=<groupname> ...]
<BR>
[--umask=<mode>]
<BR>
[--ruleperf | --noruleperf]
<BR>
[--dumpfts | --nodumpfts]
<BR>
[--dumpfjson | --nodumpfjson]
<BR>
[--quoting | --noquoting]
<BR>
[--tail | --notail]
<BR>
[--fromstart | --nofromstart]
<BR>
[--detach | --nodetach]
<BR>
[--jointbuf | --nojointbuf]
<BR>
[--keepopen | --nokeepopen]
<BR>
[--rwfifo | --norwfifo]
<BR>
[--childterm | --nochildterm]
<BR>
[--intevents | --nointevents]
<BR>
[--intcontexts | --nointcontexts]
<BR>
[--testonly | --notestonly]
<BR>
[--help] [-?]
<BR>
[--version]
</DL>
<A NAME="lbAD"> </A>
<H2>DESCRIPTION</H2>
SEC is an event correlation tool for advanced event processing which can
be harnessed for event log monitoring, for network and security management,
for fraud detection, and for any other task which involves event correlation.
Event correlation is a procedure where a stream of events is processed,
in order to detect (and act on) certain event groups that occur within
predefined time windows. Unlike many other event correlation products which
are heavyweight solutions, SEC is a lightweight and platform-independent
event correlator which runs as a single process. The user can start it as
a daemon, employ it in shell pipelines, execute it interactively in
a terminal, run many SEC processes simultaneously for different tasks,
and use it in a wide variety of other ways.
<P>
SEC reads lines from files, named pipes, or standard input,
matches the lines with patterns (regular expressions, Perl subroutines, etc.)
for recognizing input events, and
correlates events according to the rules in its configuration file(s).
Rules are matched against input in the order they are given in
the configuration file.
If there are two or more configuration files, rule sequence from every file
is matched against input (unless explicitly specified otherwise).
SEC can produce output by executing external programs (e.g.,
<B><A HREF="/cgi-bin/man/man2html?1+snmptrap">snmptrap</A></B>(1)
or
<B><A HREF="/cgi-bin/man/man2html?1+mail">mail</A></B>(1)),
by writing to files, by sending data to TCP and UDP based servers,
by calling precompiled Perl subroutines, etc.
<P>
SEC can be run in various ways. For example, the following command line
starts it as a daemon, in order to monitor events appended to the
/var/log/messages syslog file with rules from /etc/sec/syslog.rules:
<P>
/usr/bin/sec --detach --conf=/etc/sec/syslog.rules \
<BR> --input=/var/log/messages
<P>
Each time /var/log/messages is rotated, a new instance of /var/log/messages
is opened and processed from the beginning. The following command line
runs SEC in a shell pipeline, configuring it to process lines from standard
input, and to exit when the /usr/bin/nc tool closes its standard output
and exits:
<P>
/usr/bin/nc -l 8080 | /usr/bin/sec --notail --input=- \
<BR> --conf=/etc/sec/my.conf
<P>
Some SEC rules start event correlation operations, while other rules react
immediately to input events or system clock. For example, suppose that SEC
has been started with the following command line
<P>
/usr/bin/sec --conf=/etc/sec/sshd.rules --input=/var/log/secure
<P>
in order to monitor the /var/log/secure syslog file for sshd events.
Also, suppose that the /etc/sec/sshd.rules configuration file contains
the following rule for correlating SSH failed login syslog events:
<P>
type=SingleWithThreshold
<BR>
ptype=RegExp
<BR>
pattern=sshd\[\d+\]: Failed .+ for (\S+) from [\d.]+ port \d+ ssh2
<BR>
desc=Three SSH login failures within 1m for user $1
<BR>
action=pipe '%s' /bin/mail -s 'SSH login alert' <A HREF="mailto:root@localhost">root@localhost</A>
<BR>
window=60
<BR>
thresh=3
<P>
The
<I>pattern</I>
field of the rule defines the pattern for recognizing input events, while the
<I>ptype</I>
field defines its type (regular expression). Suppose that user risto fails to
log in over SSH and the following message is logged to /var/log/secure:
<P>
Dec 16 16:24:59 myserver sshd[13685]: Failed password for risto from 10.12.2.5 port 41063 ssh2
<P>
This input message will match the regular expression
pattern of the above rule, and the match variable $1 will be set to the string
<I>risto </I>
(see
<B><A HREF="/cgi-bin/man/man2html?1+perlre">perlre</A></B>(1)
for details).
After a match, SEC will evaluate the operation description string given with
the
<I>desc</I>
field. This is done by substituting $1 with its current value which yields
<I>Three SSH login failures within 1m for user risto</I>.
SEC will then check if there already exists an event correlation operation
identified with this string and triggered by the same rule.
If the operation is not found, SEC will create
a new operation for the user name risto, and the occurrence time of the input
event will be recorded into the operation.
Note that for event occurrence time SEC always uses the current time
as returned by the
<B><A HREF="/cgi-bin/man/man2html?2+time">time</A></B>(2)
system call, *not* the timestamp extracted from the event.
<P>
Suppose that after 25 seconds,
a similar SSH login failure event for the same user name is observed. In this
case, a running operation will be found for the operation description string
<I>Three SSH login failures within 1m for user risto</I>,
and the occurrence time of the second event is recorded into the operation.
If after 30 seconds a third event for the user name risto is observed,
the operation has processed 3 events within 55 seconds. Since the threshold
condition "3 events within 60 seconds" (as defined by the
<I>thresh</I>
and
<I>window</I>
fields) is now satisfied, SEC will execute the action defined with the
<I>action </I>
field -- it will fork a command
<P>
/bin/mail -s 'SSH login alert' <A HREF="mailto:root@localhost">root@localhost</A>
<P>
with a pipe connected to its standard input. Then, SEC writes the operation
description string
<I>Three SSH login failures within 1m for user risto</I>
(held by the %s special variable)
to the standard input of the command through the pipe.
In other words, an e-mail warning is sent to the local root-user.
Finally, since there are 5 seconds left until the end of
the event correlation window, the operation will consume the following SSH
login failure events for user risto without any further action, and finish
after 5 seconds.
<P>
The above example illustrates that the
<I>desc</I>
field of a rule defines the scope of event correlation and influences the
number of operations created by the rule. For example, if we set the
<I>desc </I>
field to
<I>Three SSH login failures within 1m</I>,
the root-user would be also alerted on 3 SSH login failure events
for *different* users within 1 minute.
In order to avoid clashes between operations started by different rules,
operation ID contains not only the value set by the
<I>desc</I>
field, but also the rule file name and the rule number inside the file.
For example, if the rule file /etc/sec/sshd.rules contains one rule
<P>
type=SingleWithThreshold
<BR>
ptype=RegExp
<BR>
pattern=sshd\[\d+\]: Failed .+ for (\S+) from [\d.]+ port \d+ ssh2
<BR>
desc=Three SSH login failures within 1m for user $1
<BR>
action=pipe '%s' /bin/mail -s 'SSH login alert' <A HREF="mailto:root@localhost">root@localhost</A>
<BR>
window=60
<BR>
thresh=3
<P>
and the event
<P>
Dec 16 16:24:59 myserver sshd[13685]: Failed password for risto from 10.12.2.5 port 41063 ssh2
<P>
is the first matching event for the above rule, this event will trigger
a new event correlation operation with the ID
<P>
/etc/sec/sshd.rules | 0 | Three SSH login failures within 1m for user risto
<P>
(0 is the number assigned to the first rule in the file,
see EVENT CORRELATION OPERATIONS section for more information).
<P>
The following simple example demonstrates that event correlation schemes
can be defined by combining several rules. In this example, two rules
harness contexts and synthetic events for achieving their goal:
<P>
type=SingleWithThreshold
<BR>
ptype=RegExp
<BR>
pattern=sshd\[\d+\]: Failed .+ for (\S+) from [\d.]+ port \d+ ssh2
<BR>
desc=Three SSH login failures within 1m for user $1
<BR>
action=event 3_SSH_LOGIN_FAILURES_FOR_$1
<BR>
window=60
<BR>
thresh=3
<P>
type=EventGroup
<BR>
ptype=RegExp
<BR>
pattern=3_SSH_LOGIN_FAILURES_FOR_(\S+)
<BR>
context=!USER_$1_COUNTED && !COUNTING_OFF
<BR>
count=create USER_$1_COUNTED 60
<BR>
desc=Repeated SSH login failures for 30 distinct users within 1m
<BR>
action=pipe '%s' /bin/mail -s 'SSH login alert' <A HREF="mailto:root@localhost">root@localhost</A>; \
<BR> create COUNTING_OFF 3600
<BR>
window=60
<BR>
thresh=30
<P>
The first rule looks almost identical to the rule from the previous example,
but its
<I>action</I>
field is different -- after three SSH login failures have been observed for
the same user name within one minute by an event correlation operation,
the operation will emit the synthetic event
3_SSH_LOGIN_FAILURES_FOR_<username>. Although synthetic events are created
by SEC, they are treated like regular events received from input sources and
are matched against rules.
<P>
The regular expression pattern of the second rule will match the
3_SSH_LOGIN_FAILURES_FOR_<username> event and start a new event correlation
operation if no such events have been previously seen.
Also, each time a synthetic event for some user name has matched the rule,
a context with the lifetime of 1 minute for that user name is created (see the
<I>count</I>
field).
Note that this prevents further matches for the same user name, since
a synthetic event for <username> can match the rule only if the context
USER_<username>_COUNTED *does not* exist (as requested by the boolean
expression in the
<I>context</I>
field; see CONTEXTS AND CONTEXT EXPRESSIONS section for more information).
<P>
The operation started by the second rule sends an e-mail warning to the local
root-user if 30 synthetic events have been observed within 1 minute (see the
<I>thresh</I>
and
<I>window</I>
fields). Note that due to the use of the USER_<username>_COUNTED contexts, all
synthetic events concern different user names. After sending an e-mail warning,
the operation will also create the context COUNTING_OFF with the lifetime of
1 hour, and will continue to run until the 1 minute event correlation
window expires. After the operation has finished, the presence of the
COUNTING_OFF context will keep the second rule disabled (as requested by
the boolean expression in the
<I>context</I>
field). Therefore, at most one e-mail warning per 1 hour is issued by
above rules.
<P>
The above examples have presented the event correlation capabilities of SEC
in a very brief fashion.
The following sections will provide an in-depth discussion of SEC features.
<A NAME="lbAE"> </A>
<H2>OPTIONS</H2>
<DL COMPACT>
<DT><B>--conf=<file_pattern></B>
<DD>
expand <file_pattern> to filenames (with the Perl
<B>glob</B>()
function) and read event correlation rules from every file. Multiple
<B>--conf</B>
options can be specified at command line. Each time SEC receives a signal
that forces a configuration reload, <file_pattern> is re-evaluated. See also
INPUT PROCESSING AND TIMING section for a discussion on rule processing order
for multiple configuration files.
<DT><B>--input=<file_pattern>[=<context>]</B>
<DD>
expand <file_pattern> to filenames (with the Perl
<B>glob</B>()
function) and use the files as input sources. An input file can be a regular
file, named pipe, or standard input if
<B>-</B>
was specified. Multiple
<B>--input</B>
options can be specified at command line. Each time SEC receives the
<B>SIGHUP</B>
or
<B>SIGABRT</B>
signal, <file_pattern> is re-evaluated.
If SEC experiences a system error when reading from an input file, it will
close the file (use the
<B>--reopen-timeout</B>
option for reopening the file). If <context> is given, SEC will set up the
context <context> each time it reads a line from input files that correspond
to <file_pattern>. This will help the user to write rules that match data from
particular input source(s) only. When there is an
<B>--input</B>
option with <context> specified, it will automatically enable the
<B>--intcontexts</B>
option. See INTERNAL EVENTS AND CONTEXTS section for more information.
<DT><B>--input-timeout=<input_timeout></B>, <B>--timeout-script=<timeout_script></B>
<DD>
if SEC has not observed new data in an input file during <input_timeout>
seconds (or the file was closed <input_timeout> seconds ago), <timeout_script>
will be executed with command line parameters 1 and <the name of the input
file>. If fresh data become available again, <timeout_script> will be executed
with command line parameters 0 and <the name of the input file>.
Setting <input_timeout> to 0 disables this behavior (this is also the default).
Note that
<B>--input_timeout </B>
and
<B>--timeout_script</B>
options can be used as synonyms for
<B>--input-timeout </B>
and
<B>--timeout-script</B>,
respectively.
<DT><B>--reopen-timeout=<reopen_timeout> </B>
<DD>
if an input file is in the closed state (e.g., SEC fails to open the file at
startup, because it has not been created yet), SEC will attempt
to reopen the file after every <reopen_timeout> seconds until open succeeds.
Setting <reopen_timeout> to 0 disables this behavior (this is also the default).
This option has no meaning when the
<B>--notail</B>
option is also specified.
Note that
<B>--reopen_timeout</B>
is a synonym for
<B>--reopen-timeout</B>.
<DT><B>--check-timeout=<check_timeout></B>
<DD>
if SEC has not observed new data in an input file, the file will not be polled
(both for status and data) during the next <check_timeout> seconds.
Setting <check_timeout> to 0 disables this behavior (this is also the default).
Note that
<B>--check_timeout</B>
is a synonym for
<B>--check-timeout</B>.
<DT><B>--poll-timeout=<poll_timeout></B>
<DD>
a real number that specifies how many seconds SEC will sleep when no new data
were read from input files. Default is 0.1 seconds.
Note that
<B>--poll_timeout</B>
is a synonym for
<B>--poll-timeout</B>.
<DT><B>--socket-timeout=<socket_timeout></B>
<DD>
if a network connection to a remote peer can't be established within
<socket_timeout> seconds, give up. Default is 60 seconds.
Note that
<B>--socket_timeout</B>
is a synonym for
<B>--socket-timeout</B>.
<DT><B>--blocksize=<io_block_size></B>
<DD>
the number of bytes SEC will attempt to read at once from an input file.
Default is 8192 bytes (i.e., read from input files by 8KB blocks).
<DT><B>--bufsize=<input_buffer_size></B>
<DD>
set all input buffers to hold <input_buffer_size> lines.
The content of input buffers will be compared with
patterns that are part of rule definitions (i.e., no more than
<input_buffer_size> lines can be matched by a pattern at a time).
If <input_buffer_size> is set to 0, SEC will determine the proper value
for <input_buffer_size> by checking event matching patterns of all SEC rules.
Default is 0 (i.e., determine the size of input buffers automatically).
<DT><B>--evstoresize=<event_store_size></B>
<DD>
set an upper limit to the number of events in context event stores.
Default is 0 which sets no limit.
<DT><B>--cleantime=<clean_time></B>
<DD>
time interval in seconds that specifies how often internal event correlation
and context lists are processed, in order to accomplish time-related tasks
and to remove obsolete elements. See INPUT PROCESSING AND TIMING section for
more information.
Default is 1 second.
<DT><B>--log=<logfile></B>
<DD>
use <logfile> for logging SEC activities. Note that if the SEC standard error
is connected to a terminal, messages will also be logged there, in order to
facilitate debugging.
<DT><B>--syslog=<facility></B>
<DD>
use syslog for logging SEC activities. All messages will be logged with the
facility <facility>, e.g.,
<I>local0</I>
(see
<B><A HREF="/cgi-bin/man/man2html?3+syslog">syslog</A></B>(3)
for possible facility values). Warning: be careful with using this option if
SEC is employed for monitoring syslog log files, because message loops might
occur.
<DT><B>--debug=<debuglevel></B>
<DD>
set logging verbosity for SEC. Setting debuglevel to <debuglevel>
means that all messages of level <debuglevel> and lower are logged (e.g.,
if <debuglevel> is 3, messages from levels 1-3 are logged). The
following levels are recognized by SEC:
<BR>
1 - critical messages (severe faults that cause SEC to terminate, e.g.,
a failed system call)
<BR>
2 - error messages (faults that need attention, e.g., an incorrect rule
definition in a configuration file)
<BR>
3 - warning messages (possible faults, e.g., a command forked from SEC
terminated with a non-zero exit code)
<BR>
4 - notification messages (normal system level events and interrupts, e.g.,
the reception of a signal)
<BR>
5 - informative messages (information about external programs forked
from SEC)
<BR>
6 - debug messages (detailed information about all SEC activities)
<BR>
Default <debuglevel> is 6 (i.e., log everything). See SIGNALS section
for information on how to change <debuglevel> at runtime.
<DT><B>--pid=<pidfile></B>
<DD>
SEC will store its process ID to <pidfile> at startup.
<DT><B>--dump=<dumpfile></B>
<DD>
SEC will use <dumpfile> as its dump file for writing performance and debug
data. With the
<B>--dumpfts</B>
option, a timestamp suffix is appended to the dump file name. With the
<B>--dumpfjson</B>
option, dump file is produced in JSON format.
See SIGNALS section for more information. Default is /tmp/sec.dump.
<DT><B>--user=<username></B>, <B>--group=<groupname></B>
<DD>
if SEC is started with effective user ID 0, it will drop root privileges by
switching to user <username> and group <groupname>.
The
<B>--group</B>
option can't be used without the
<B>--user</B>
option. If the
<B>--user</B>
option is given without
<B>--group</B>,
primary group of the user <username> is assumed for <groupname>.
If several groups are provided with multiple
<B>--group</B>
options, SEC switches to the first group with other groups as supplementary
groups.
<DT><B>--umask=<mode></B>
<DD>
set file mode creation mask to <mode> at SEC startup, where <mode>
is a value from the range 0..0777 (see also
<B><A HREF="/cgi-bin/man/man2html?2+umask">umask</A></B>(2)).
Octal, decimal, hexadecimal, and binary values can be specified for <mode>
(e.g., octal mask 0027 can also be expressed as 23, 0x17, and 0b000010111).
<DT><B>--ruleperf</B>, <B>--noruleperf</B>
<DD>
if the
<B>--ruleperf</B>
option is specified, performance data (e.g., total consumed CPU time)
is collected for each rule and reported in dump file. Default is
<B>--noruleperf</B>.
<DT><B>--dumpfts</B>, <B>--nodumpfts</B>
<DD>
if the
<B>--dumpfts</B>
option is specified, a timestamp suffix (seconds since Epoch) is appended
to the dump file name that reflects the file creation time. Default is
<B>--nodumpfts</B>.
<DT><B>--dumpfjson</B>, <B>--nodumpfjson</B>
<DD>
if the
<B>--dumpfjson</B>
option is specified, dump file is produced in JSON format.
Default is
<B>--nodumpfjson</B>.
<DT><B>--quoting</B>, <B>--noquoting</B>
<DD>
if the
<B>--quoting</B>
option is specified, operation description strings that are supplied to
command lines of
<I>shellcmd</I>,
<I>spawn</I>,
and
<I>cspawn</I>
actions will be put inside single quotes. Each single quote (') that strings
originally contain will be masked. This option prevents the shell from
interpreting special symbols that operation description strings might contain.
Default is
<B>--noquoting</B>.
<DT><B>--tail</B>, <B>--notail</B>
<DD>
if the
<B>--notail</B>
option is specified, SEC will process all data that are currently available
in input files and exit after reaching all EOFs.
If all input is received from a pipe and the
<B>--notail</B>
option is given, SEC terminates when the last writer closes the pipe
(EOF condition). Please note that with named pipes
<B>--notail</B>
should be used with
<B>--norwfifo</B>.
With the
<B>--tail</B>
option, SEC will jump to the end of input files and wait for new lines to
arrive.
Each input file is tracked both by its name and i-node, and
input file rotations are handled seamlessly.
If the input file is recreated or truncated, SEC will reopen it and process
its content from the beginning. If the input file is removed (i.e., there is
just an i-node left without a name), SEC will keep the i-node open and wait
for the input file recreation.
Default is
<B>--tail</B>.
<DT><B>--fromstart</B>, <B>--nofromstart</B>
<DD>
these flags have no meaning when the
<B>--notail</B>
option is also specified. When used in combination with
<B>--tail</B>
(or alone, since
<B>--tail</B>
is enabled by default),
<B>--fromstart</B>
will force SEC to read and process input files from the beginning to
the end, before the 'tail' mode is entered. Default is
<B>--nofromstart</B>.
<DT><B>--detach</B>, <B>--nodetach</B>
<DD>
if the
<B>--detach</B>
option is specified, SEC will disassociate itself from the controlling
terminal and become a daemon at startup (note that SEC will close its standard
input, standard output, and standard error, and change its working directory
to the root directory). Default is
<B>--nodetach</B>.
<DT><B>--jointbuf</B>, <B>--nojointbuf</B>
<DD>
if the
<B>--jointbuf</B>
option is specified, SEC uses joint input buffer for all input sources
(the size of the buffer is set with the
<B>--bufsize</B>
option). The
<B>--nojointbuf</B>
option creates a separate input buffer for each input file, and a separate
buffer for all synthetic and internal events (the sizes of all buffers are
set with the
<B>--bufsize</B>
option). The
<B>--jointbuf</B>
option allows multiline patterns to match lines from several input
sources, while the
<B>--nojointbuf </B>
pattern restricts the matching to lines from one input source only.
See INPUT PROCESSING AND TIMING section for more information.
If the size of input buffer(s) is 1 (either explicitly set with
<B>--bufsize=1</B>
or automatically determined from SEC rules),
<B>--jointbuf</B>
option is enabled, otherwise the default is
<B>--nojointbuf</B>.
<DT><B>--keepopen</B>, <B>--nokeepopen</B>
<DD>
if the
<B>--keepopen</B>
option is specified, SEC will keep input files open across soft restarts.
When the
<B>SIGABRT</B>
signal is received, SEC will not reopen input files which have been opened
previously, but will only open input files which are in the closed state.
The
<B>--nokeepopen </B>
option forces SEC to close and (re)open all input files during soft restarts.
Default is
<B>--keepopen</B>.
<DT><B>--rwfifo</B>, <B>--norwfifo</B>
<DD>
if the
<B>--norwfifo</B>
option is specified, named pipe input files are opened in read-only mode.
In this mode, the named pipe has to be reopened when the last writer
closes the pipe, in order to clear the EOF condition on the pipe. With the
<B>--rwfifo</B>
option, named pipe input files are opened in read-write mode, although
SEC never writes to the pipes. In this mode, the pipe does not need to be
reopened when an external writer closes it, since there is always at least
one writer on the pipe and EOF will never appear. Therefore, if the
<B>--notail</B>
option has been given,
<B>--norwfifo</B>
should also be specified.
Default is
<B>--rwfifo</B>.
<DT><B>--childterm</B>, <B>--nochildterm</B>
<DD>
if the
<B>--childterm</B>
option is specified, SEC will send the
<B>SIGTERM </B>
signal to all its child processes
when it terminates or goes through a full restart. Default is
<B>--childterm</B>.
<DT><B>--intevents</B>, <B>--nointevents</B>
<DD>
SEC will generate internal events when it starts up, when it receives
certain signals, and when it terminates gracefully. Specific rules can be
written to match those internal events, in order to accomplish special
tasks at SEC startup, restart, and shutdown.
See INTERNAL EVENTS AND CONTEXTS section for more information. Default is
<B>--nointevents</B>.
<DT><B>--intcontexts</B>, <B>--nointcontexts</B>
<DD>
SEC will create an internal context when it reads a line from an input file.
This will help the user to write rules that match data from particular input
source only. See INTERNAL EVENTS AND CONTEXTS section for more information.
Default is
<B>--nointcontexts</B>.
<DT><B>--testonly</B>, <B>--notestonly</B>
<DD>
if the
<B>--testonly</B>
option is specified, SEC will exit immediately after parsing the configuration
file(s). If the configuration file(s) contained no faulty rules, SEC will exit
with 0, otherwise with 1. Default is
<B>--notestonly</B>.
<DT><B>--help</B>, <B>-?</B>
<DD>
SEC will output usage information and exit.
<DT><B>--version</B>
<DD>
SEC will output version information and exit.
</DL>
<P>