source: trunk/man/samhainrc.5 @ 169

Last change on this file since 169 was 169, checked in by katerina, 14 years ago

Fixes for tickes #93 to #104 (yes, big commit, bad, bad,...).

File size: 21.5 KB
Line 
1.TH SAMHAINRC 5 "Jul 29, 2004" "" "samhainrc manual"
2.SH NAME
3samhainrc \- samhain(8) configuration file
4
5.SH WARNING
6.PP
7The information in this man page is not always up to date.
8The authoritative documentation is the user manual.
9
10.SH DESCRIPTION
11.PP
12The configuration file for
13.BR samhain (8)
14is named
15.I samhainrc
16and located in
17.I /etc
18by default.
19.PP
20It contains several sections, indicated by headings in square brackets.
21Each section may hold zero or more
22.BI key= value
23pairs. Blank lines and lines starting with '#' are comments.
24Everything before the first section and after an
25.I "[EOF]"
26is ignored. The file may be (clear text) signed by PGP/GnuPG, and
27.B samhain
28may invoke GnuPG to check the signature
29if compiled with support for it.
30.PP
31Conditional inclusion of entries for some host(s) is
32supported via any number of
33.BI @ hostname /@ end
34directives.
35.BI @ hostname
36and
37.BI @ end
38must each be on separate lines. Lines in between will only be
39read if
40.I "hostname"
41(which may be a regular expression) matches the local host.
42.PP
43Likewise, conditional inclusion of entries based on system type is
44supported via any number of
45.BI $ sysname:release:machine /$ end
46directives.
47.br
48.I "sysname:release:machine"
49can be inferred from
50.I "uname -srm"
51and may be a regular expression.
52.PP
53Filenames/directories to check may be wildcard patterns.
54.PP
55Options given on the command line will override
56those in the configuration file.
57The recognized sections in the configuration file are as follows:
58.PP
59Boolean options can be set with any of 1|true|yes or 0|false|no.
60.TP
61.I "[ReadOnly]"
62This section may contain
63.br
64.BI file= PATH
65and
66.br
67.BI dir= [depth]PATH
68entries for files and directories to check. All modifications except access
69times will be reported for these files.
70.I [depth] (use without brackets)
71is an optional parameter to define a per\-directory recursion
72depth.
73.TP
74.I "[LogFiles]"
75As above, but modifications of timestamps, file size, and signature will
76be ignored.
77.TP
78.I "[GrowingLogFiles]"
79As above, but modifications of file size will only be ignored if the size has
80.IR increased .
81.TP
82.I "[Attributes]"
83As above, but only modifications of ownership and access permissions
84will be checked.
85.TP
86.I "[IgnoreAll]"
87As above, but report no modifications for
88these files/directories. Access failures
89will still be reported.
90.TP
91.I "[IgnoreNone]"
92As above, but report all modifications for these files/directories,
93including access time.
94.TP
95.I "[User0]"
96.TP
97.I "[User1]"
98.TP
99.I "[User2]"
100.TP
101.I "[User3]"
102.TP
103.I "[User4]"
104These are reserved for user-defined policies.
105.TP
106.I "[Prelink]"
107For prelinked executables / libraries or directories holding them.
108.TP
109.I "[Log]"
110This section defines the filtering rules for logging.
111It may contain the following entries:
112.br
113.BI  MailSeverity= val
114where the threshold value
115.I val
116may be one of
117.IR debug ,
118.IR info ,
119.IR notice ,
120.IR warn ,
121.IR mark ,
122.IR err ,
123.IR crit ,
124.IR alert ,
125or
126.IR none .
127By default, everything equal to and above the threshold will be logged.
128The specifiers
129.IR * ,
130.IR ! ,
131and
132.I =
133are interpreted as 'all', 'all but', and 'only', respectively (like
134in the Linux version of syslogd(8)).
135Time stamps have the priority
136.IR warn ,
137system\-level errors have the priority
138.IR err ,
139and important start\-up messages the priority
140.IR alert .
141The signature key for the log file will never be logged to syslog or the
142log file itself.
143For failures to verify file integrity, error levels are defined
144in the next section.
145.br
146.BI  PrintSeverity= val,
147.br
148.BI  LogSeverity= val,
149.br
150.BI  ExportSeverity= val,
151.br
152.BI  ExternalSeverity= val,
153.br
154.BI  PreludeSeverity= val,
155.br
156.BI  DatabaseSeverity= val,
157and
158.br
159.BI  SyslogSeverity= val
160set the thresholds for logging via stdout (or
161.IR /dev/console ),
162log file, TCP forwarding, calling external programs,
163and
164.BR syslog (3).
165.TP
166.I "[EventSeverity]"
167.BI  SeverityReadOnly= val,
168.br
169.BI  SeverityLogFiles= val,
170.br
171.BI  SeverityGrowingLogs= val,
172.br
173.BI  SeverityIgnoreNone= val,
174.br
175.BI  SeverityIgnoreAll= val,
176.br
177.BI  SeverityPrelink= val,
178.br
179.BI  SeverityUser0= val,
180.br
181.BI  SeverityUser1= val,
182.br
183.BI  SeverityUser2= val,
184.br
185.BI  SeverityUser3= val,
186and
187.br
188.BI  SeverityUser4= val
189define the error levels for failures to verify the integrity of
190files/directories of the respective types. I.e. if such a file shows
191unexpected modifications, an error of level
192.I val
193will be generated, and logged to all facilities with a threshold of at least
194.IR val .
195.br
196.BI  SeverityFiles= val
197sets the error level for file access problems, and
198.br
199.BI  SeverityDirs= val
200for directory access problems.
201.br
202.BI SeverityNames= val
203sets the error level for obscure file names
204(e.g. non\-printable characters), and for files
205with invalid UIDs/GIDs.
206.TP
207.I "[External]"
208.BI OpenCommand= path
209Start the definition of an external logging program|script.
210.br
211.BI SetType= log|srv
212Type/purpose of program (log for logging).
213.br
214.BI SetCommandline= list
215Command line options.
216.br
217.BI SetEnviron= KEY=val
218Environment for external program.
219.br
220.BI SetChecksum= val
221Checksum of the external program (checked before invoking).
222.br
223.BI SetCredentials= username
224User as who the program will run.
225.br
226.BI SetFilterNot= list
227Words not allowed in message.
228.br
229.BI SetFilterAnd= list
230Words required (ALL) in message.
231.br
232.BI SetFilterOr= list
233Words required (at least one) in message.
234.br
235.BI SetDeadtime= seconds
236Time between consecutive calls.
237.TP
238.I "[Utmp]"
239Configuration for watching login/logout events.
240.br
241.BI LoginCheckActive= 0|1
242Switch off/on login/logout reporting.
243.br
244.BI LoginCheckInterval= val
245Interval (seconds) between checks for login/logout events.
246.br
247.BI SeverityLogin= val
248.br
249.BI SeverityLoginMulti= val
250.br
251.BI SeverityLogout= val
252Severity levels for logins, multiple logins
253by same user, and logouts.
254.TP
255.I "[Kernel]"
256Configuration for detecting kernel rootkits.
257.br
258.BI KernelCheckActive= 0|1
259Switch off/on checking of kernel syscalls to detect kernel module rootkits.
260.br
261.BI KernelCheckInterval= val
262Interval (seconds) between checks.
263.br
264.BI SeverityKernel= val
265Severity level for clobbered kernel syscalls.
266.br
267.BI KernelCheckIDT= 0|1
268Whether to check the interrrupt descriptor table.
269.br
270.BI KernelSystemCall= address
271The address of system_call (grep system_call System.map).
272Required after a kernel update.
273.br
274.BI KernelProcRoot= address
275The address of proc_root (grep ' proc_root$' System.map).
276Required after a kernel update.
277.br
278.BI KernelProcRootIops= address
279The address of proc_root_inode_operations
280(grep proc_root_inode_operations System.map).
281Required after a kernel update.
282.br
283.BI KernelProcRootLookup= address
284The address of proc_root_lookup (grep proc_root_lookup System.map).
285Required after a kernel update.
286.TP
287.I "[SuidCheck]"
288Settings for finding SUID/SGID files on disk.
289.br
290.BI SuidCheckActive= 0|1
291Switch off/on the check.
292.br
293.BI SuidCheckExclude= path
294  A directory (and its subdirectories)
295  to exclude from the check. Only one directory can be specified this way.
296.br
297.BI SuidCheckSchedule= schedule
298Crontab-like schedule for checks.
299.br
300.BI SeveritySuidCheck= severity
301Severity for events.
302.br
303.BI SuidCheckFps= fps
304Limit files per seconds for SUID check.
305.br
306.BI SuidCheckNosuid= 0|1
307Check filesystems mounted as nosuid. Defaults to not.
308.br
309.BI SuidCheckQuarantineFiles= 0|1
310Whether to quarantine files. Defaults to not.
311.br
312.BI SuidCheckQuarantineMethod= 0|1|2
313Quarantine method. Delete = 1, remove suid/sgid flags = 1, move to quarantine directory = 2. Defaults to 1 (remove suid/sgid flags).
314.br
315.BI
316.TP
317.I "[Mounts]"
318Configuration for checking mounts.
319.br
320.BI MountCheckActive= 0|1
321Switch off/on this module.
322.br
323.BI MountCheckInterval= seconds
324  The interval between checks (default 300).
325.br
326.BI SeverityMountMissing= severity
327Severity for reports on missing mounts.
328.br
329.BI SeverityOptionMissing= severity
330Severity for reports on missing mount options.
331.br
332.BI CheckMount= path
333[mount_options]
334.br
335Mount point to check. Mount options must be given as
336comma-separated list, separated by a blank from the preceding mount point.
337.TP
338.I "[UserFiles]"
339Configuration for checking paths relative to user home directories.
340.br
341.BI UserFilesActive= 0|1
342Switch off/on this module.
343.br
344.BI UserFilesName= filename
345policy
346.br
347Files to check for under each $HOME. Allowed values for 'policy'
348are: allignore, attributes, logfiles, loggrow, noignore (default),
349readonly, user0, user1, user2, user3, and user4.
350.br
351.BI UserFilesCheckUids= uid_list
352A list of UIDs where we want to check. The default
353is all. Ranges (e.g. 100-500) are allowed. If there is an open range (e.g.
3541000-), it must be last in the list.
355.TP
356.I "[ProcessCheck]"
357Settings for finding hidden/fake,required processes on the local host.
358.br
359.BI ProcessCheckActive= 0|1
360Switch off/on the check.
361.br
362.BI ProcessCheckInterval= seconds
363  The interval between checks (default 300).
364.br
365.BI SeverityProcessCheck= severity
366Severity for events (default crit).
367.br
368.BI ProcessCheckMinPID= pid
369The minimum PID to check (default 0).
370.br
371.BI ProcessCheckMaxPID= pid
372The maximum PID to check (default 32767).
373.br
374.BI ProcessCheckPSPath= path
375The path to ps (autodetected at compile time).
376.br
377.BI ProcessCheckPSArg= argument
378The argument to ps (autodetected at compile time).
379Must yield PID in first column.
380.br
381.BI ProcessCheckExists= regular_expression
382Check for existence of a process matching the given regular expression.
383.TP
384.I "[PortCheck]"
385Settings for checking open ports on the local host.
386.br
387.BI PortCheckActive= 0|1
388Switch off/on the check.
389.br
390.BI PortCheckInterval= seconds
391  The interval between checks (default 300).
392.br
393.BI PortCheckUDP= yes|no
394Whether to check UPD ports as well (default yes).
395.br
396.BI SeverityPortCheck= severity
397Severity for events (default crit).
398.br
399.BI PortCheckInterface= ip_address
400Additional interface to check.
401.br
402.BI PortCheckOptional= ip_address:list
403Ports that may, but need not be open. The ip_address is the one
404of the interface, the list must be
405comma or whitespace separated, each item must be (port|service)/protocol,
406e.g. 22/tcp,nfs/tcp/nfs/udp.
407.br
408.BI PortCheckRequired= ip_address:list
409Ports that are required to be open. The ip_address is the one
410of the interface, the list must be
411comma or whitespace separated, each item must be (port|service)/protocol,
412e.g. 22/tcp,nfs/tcp/nfs/udp.
413.TP
414.I "[Database]"
415Settings for
416.I logging
417to a database.
418.br
419.BI SetDBHost= db_host
420Host where the DB server runs (default: localhost).
421Should be a numeric IP address for PostgreSQL.
422.br
423.BI SetDBName= db_name
424Name of the database (default: samhain).
425.br
426.BI SetDBTable= db_table
427Name of the database table (default: log).
428.br
429.BI SetDBUser= db_user
430Connect as this user (default: samhain).
431.br
432.BI SetDBPassword= db_password
433Use this password (default: none).
434.br
435.BI SetDBServerTstamp= true|false
436Log server timestamp for client messages (default: true).
437.br
438.BI UsePersistent= true|false
439Use a persistent connection (default: true).
440.TP
441.I "[Misc]"
442.BI Daemon= no|yes
443Detach from controlling terminal to become a daemon.
444.br
445.BI  MessageHeader= format
446Costom format for message header. Replacements:
447.I %F
448source file name,
449.I %L
450source file line,
451.I %S
452severity,
453.I %T
454timestamp,
455.I %C
456message class.
457.br
458.BI VersionString= string
459Set version string to include in file signature database
460(along with hostname and date).
461.br
462.BI SetReverseLookup= true|false
463If false, skip reverse lookups when connecting to a host known by name
464rather than IP address.
465.br
466.BI  HideSetup= yes|no
467Don't log name of config/database files on startup.
468.br
469.BI  SyslogFacility= facility
470Set the syslog facility to use. Default is LOG_AUTHPRIV.
471.br
472.BI MACType= HASH-TIGER|HMAC-TIGER
473Set type of message authentication code (HMAC).
474Must be identical on client and server.
475.br
476.BI SetLoopTime= val
477Defines the interval (in seconds) for timestamps.
478.br
479.BI SetConsole= device
480Set the console device (default /dev/console).
481.br
482.BI MessageQueueActive= 1|0
483Whether to use a SysV IPC message queue.
484.br
485.BI PreludeMapToInfo= list of severities
486The severities (see section
487.IR [Log] )
488that should be mapped to impact
489severity
490.I info
491in prelude.
492.br
493.BI PreludeMapToLow= list of severities
494The severities (see section
495.IR [Log] )
496that should be mapped to impact
497severity
498.I low
499in prelude.
500.br
501.BI PreludeMapToMedium= list of severities
502The severities (see section
503.IR [Log] )
504that should be mapped to impact
505severity
506.I medium
507in prelude.
508.br
509.BI PreludeMapToHigh= list of severities
510The severities (see section
511.IR [Log] )
512that should be mapped to impact
513severity
514.I high
515in prelude.
516.br
517.BI SetMailTime= val
518defines the maximum interval (in seconds) between succesive e\-mail reports.
519Mail might be empty if there are no events to report.
520.br
521.BI SetMailNum= val
522defines the maximum number of messages that are stored before e\-mailing them.
523Messages of highest priority are always sent immediately.
524.br
525.BI SetMailAddress= username @ host
526sets the recipient address for mailing.
527.I "No aliases should be used."
528For security, you should prefer a numerical host address.
529.br
530.BI SetMailRelay= server
531sets the hostname for the mail relay server (if you need one).
532If no relay server is given, mail is sent directly to the host given in the
533mail address, otherwise it is sent to the relay server, who should
534forward it to the given address.
535.br
536.BI SetMailSubject= val
537defines a custom format for the subject of an email message.
538.br
539.BI SetMailSender= val
540defines the sender for the 'From:' field of a message.
541.br
542.BI SetMailFilterAnd= list
543defines a list of strings all of which must match a message, otherwise
544it will not be mailed.
545.br
546.BI SetMailFilterOr= list
547defines a list of strings at least one of which must match a message, otherwise
548it will not be mailed.
549.br
550.BI SetMailFilterNot= list
551defines a list of strings none of which should match a message, otherwise
552it will not be mailed.
553.br
554.BI SamhainPath= /path/to/binary
555sets the path to the samhain binary. If set, samhain will checksum
556its own binary both on startup and termination, and compare both.
557.br
558.BI SetBindAddress= IP_address
559The IP address (i.e. interface on multi-interface box) to use
560for outgoing connections.
561.br
562.BI SetTimeServer= server
563sets the hostname for the time server.
564.br
565.BI TrustedUser= name|uid
566Add a user to the set of trusted users (root and the effective user
567are always trusted. You can add up to 7 more users).
568.br
569.BI SetLogfilePath= AUTO|/path
570Path to logfile (AUTO to tack hostname on compiled-in path).
571.br
572.BI SetLockfilePath= AUTO|/path
573Path to lockfile (AUTO to tack hostname on compiled-in path).
574.TP
575.B Standalone or client only
576.br
577.BI SetNiceLevel= -19..19
578Set scheduling priority during file check.
579.br
580.BI SetIOLimit= bps
581Set IO limits (kilobytes per second) for file check.
582.br
583.BI SetFilecheckTime= val
584Defines the interval (in seconds) between succesive file checks.
585.br
586.BI FileCheckScheduleOne= schedule
587Crontab-like schedule for file checks. If used,
588.I SetFilecheckTime
589is ignored.
590.br
591.BI UseHardlinkCheck= yes|no
592Compare number of hardlinks to number of subdirectories for directories.
593.br
594.BI HardlinkOffset= N:/path
595Exception (use multiple times for multiple
596exceptions). N is offset (actual - expected hardlinks) for /path.
597.br
598.BI AddOKChars= N1,N2,..
599List of additional acceptable characters (byte value(s)) for the check for
600weird filenames. Nn may be hex (leading '0x': 0xNN), octal
601(leading zero: 0NNN), or decimal.
602Use
603.I all
604for all.
605.br
606.BI FilenamesAreUTF8= yes|no
607Whether filenames are UTF-8 encoded (defaults to no). If yes, filenames
608are checked for invalid UTF-8 encoding and for ending in invisible characters.
609.br
610.BI IgnoreAdded= path_regex
611Ignore if this file/directory is added/created.
612.br
613.BI IgnoreMissing= path_regex
614Ignore if this file/directory is missing/deleted.
615.br
616.BI ReportOnlyOnce= yes|no
617Report only once on a modified file (default yes).
618.br
619.BI  ReportFullDetail= yes|no
620Report in full detail on modified files (not only modified items).
621.br
622.BI UseLocalTime= yes|no
623Report file timestamps in local time rather than GMT (default no).
624Do not use this with Beltane.
625.br
626.BI  ChecksumTest= {init|update|check|none}
627defines whether to initialize/update the database or verify files against it.
628If 'none', you should supply the required option on the command line.
629.br
630.BI SetPrelinkPath= path
631Path of the prelink executable (default /usr/sbin/prelink).
632.br
633.BI SetPrelinkChecksum= checksum
634TIGER192 checksum of the prelink executable (no default).
635.br
636.BI SetLogServer= server
637sets the hostname for the log server.
638.br
639.BI SetServerPort= portnumber
640sets the port on the server to connect to.
641.br
642.BI SetDatabasePath= AUTO|/path
643Path to database (AUTO to tack hostname on compiled-in path).
644.br
645.BI DigestAlgo= SHA1|MD5
646Use SHA1 or MD5 instead of the TIGER checksum (default: TIGER192).
647.br
648.BI RedefReadOnly= +/-XXX,+/-YYY,...
649Add or subtract tests XXX from the ReadOnly policy.
650Tests are: CHK (checksum), TXT (store literal content), LNK (link),
651HLN (hardlink), INO (inode), USR (user), GRP (group), MTM (mtime),
652ATM (atime), CTM (ctime), SIZ (size), RDEV (device numbers)
653and/or MOD (file mode).
654.br
655.BI RedefAttributes= +/-XXX,+/-YYY,...
656Add or subtract tests XXX from the Attributes policy.
657.br
658.BI RedefLogFiles= +/-XXX,+/-YYY,...
659Add or subtract tests XXX from the LogFiles policy.
660.br
661.BI RedefGrowingLogFiles= +/-XXX,+/-YYY,...
662Add or subtract tests XXX from the GrowingLogFiles policy.
663.br
664.BI RedefIgnoreAll= +/-XXX,+/-YYY,...
665Add or subtract tests XXX from the IgnoreAll policy.
666.br
667.BI RedefIgnoreNone= +/-XXX,+/-YYY,...
668Add or subtract tests XXX from the IgnoreNone policy.
669.br
670.BI RedefUser0= +/-XXX,+/-YYY,...
671Add or subtract tests XXX from the User0 policy.
672.br
673.BI RedefUser1= +/-XXX,+/-YYY,...
674Add or subtract tests XXX from the User1 policy.
675.br
676.BI RedefUser2= +/-XXX,+/-YYY,...
677Add or subtract tests XXX from the User2 policy.
678.br
679.BI RedefUser3= +/-XXX,+/-YYY,...
680Add or subtract tests XXX from the User3 policy.
681.br
682.BI RedefUser4= +/-XXX,+/-YYY,...
683Add or subtract tests XXX from the User4 policy.
684.TP
685.B Server Only
686.br
687.BI SetUseSocket= yes|no
688If unset, do not open the command socket. The default is no.
689.br
690.BI SetSocketAllowUid= UID
691Which user can connect to the command socket. The default is 0 (root).
692.br
693.BI SetSocketPassword= password
694Password (max. 14 chars, no '@') for password-based authentication on the
695command socket (only if the OS does not support passing
696credentials via sockets).
697.br
698.BI SetChrootDir= path
699If set, chroot to this directory after startup.
700.br
701.BI SetStripDomain= yes|no
702Whether to strip the domain from the client hostname when
703logging client messages (default: yes).
704.br
705.BI SetClientFromAccept= true|false
706If true, use client address as known to the communication layer. Else
707(default) use client name as claimed by the client, try to verify against
708the address known to the communication layer, and accept
709(with a warning message) even if this fails.
710.br
711.BI  UseClientSeverity= yes|no
712Use the severity of client messages.
713.br
714.BI  UseClientClass= yes|no
715Use the class of client messages.
716.br
717.BI SetServerPort= number
718The port that the server should use for listening (default is 49777).
719.br
720.BI SetServerInterface= IPaddress
721The IP address (i.e. interface on multi-interface box) that the
722server should use for listening (default is all). Use INADDR_ANY to reset
723to all.
724.br
725.BI  SeverityLookup= severity
726Severity of the message on client address != socket peer.
727.br
728.BI UseSeparateLogs= true|false
729If true, messages from different clients will be logged to separate
730log files (the name of the client will be appended to the name of the main
731log file to construct the logfile name).
732.br
733.BI  SetClientTimeLimit= seconds
734The maximum time between client messages. If exceeded, a warning will
735be issued (the default is 86400 sec = 1 day).
736.br
737.BI SetUDPActive= yes|no
738yule 1.2.8+: Also listen on 514/udp (syslog).
739
740
741.TP
742.I "[Clients]"
743This section is only relevant if
744.B samhain
745is run as a log server for clients running on another (or the same) machine.
746.br
747.BI Client= hostname @ salt @ verifier
748registers a client at host
749.I hostname
750(fully qualified hostname required) for access to the
751log server.
752Log entries from unregistered clients will not be accepted.
753To generate a salt and a valid verifier, use the command
754.B "samhain -P"
755.IR "password" ,
756where
757.I password
758is the password of the client. A simple utility program
759.B samhain_setpwd
760is provided to re\-set the compiled\-in default password of the client
761executable to a user\-defined
762value.
763.TP
764.I "[EOF]"
765An optional end marker. Everything below is ignored.
766
767.SH SEE ALSO
768.PP
769.BR samhain (8)
770
771.SH AUTHOR
772.PP
773Rainer Wichmann (http://la\-samhna.de)
774
775.SH BUG REPORTS
776.PP
777If you find a bug in
778.BR samhain ,
779please send electronic mail to
780.IR support@la\-samhna.de .
781Please include your operating system and its revision, the version of
782.BR samhain ,
783what C compiler you used to compile it, your 'configure' options, and
784anything else you deem helpful.
785
786.SH COPYING PERMISSIONS
787.PP
788Copyright (\(co) 2000, 2004, 2005 Rainer Wichmann
789.PP
790Permission is granted to make and distribute verbatim copies of
791this manual page provided the copyright notice and this permission
792notice are preserved on all copies.
793.ig
794Permission is granted to process this file through troff and print the
795results, provided the printed document carries copying permission
796notice identical to this one except for the removal of this paragraph
797(this paragraph not being relevant to the printed manual page).
798..
799.PP
800Permission is granted to copy and distribute modified versions of this
801manual page under the conditions for verbatim copying, provided that
802the entire resulting derived work is distributed under the terms of a
803permission notice identical to this one.
804
Note: See TracBrowser for help on using the repository browser.