NAME
samhainrc - samhain(8) configuration file
WARNING
The information in this man page is not always up to date. The
authoritative documentation is the user manual.
DESCRIPTION
The configuration file for samhain(8) is named samhainrc and located in
/etc by default.
It contains several sections, indicated by headings in square brackets.
Each section may hold zero or more key=value pairs. Blank lines and
lines starting with ’#’ are comments. Everything before the first
section and after an [EOF] is ignored. The file may be (clear text)
signed by PGP/GnuPG, and samhain may invoke GnuPG to check the
signature if compiled with support for it.
Conditional inclusion of entries for some host(s) is supported via any
number of @hostname/@end directives. @hostname and @end must each be
on separate lines. Lines in between will only be read if hostname
(which may be a regular expression) matches the local host.
Likewise, conditional inclusion of entries based on system type is
supported via any number of $sysname:release:machine/$end directives.
sysname:release:machine can be inferred from uname -srm and may be a
regular expression.
Filenames/directories to check may be wildcard patterns.
Options given on the command line will override those in the
configuration file. The recognized sections in the configuration file
are as follows:
Boolean options can be set with any of 1|true|yes or 0|false|no.
[ReadOnly]
This section may contain
file=PATH and
dir=[depth]PATH entries for files and directories to check. All
modifications except access times will be reported for these
files. [depth] (use without brackets) is an optional parameter
to define a per-directory recursion depth.
[LogFiles]
As above, but modifications of timestamps, file size, and
signature will be ignored.
[GrowingLogFiles]
As above, but modifications of file size will only be ignored if
the size has increased.
[Attributes]
As above, but only modifications of ownership and access
permissions will be checked.
[IgnoreAll]
As above, but report no modifications for these
files/directories. Access failures will still be reported.
[IgnoreNone]
As above, but report all modifications for these
files/directories, including access time.
[User0]
[User1]
[User2]
[User3]
[User4]
These are reserved for user-defined policies.
[Prelink]
For prelinked executables / libraries or directories holding
them.
[Log] This section defines the filtering rules for logging. It may
contain the following entries:
MailSeverity=val where the threshold value val may be one of
debug, info, notice, warn, mark, err, crit, alert, or none. By
default, everything equal to and above the threshold will be
logged. The specifiers *, !, and = are interpreted as ’all’,
’all but’, and ’only’, respectively (like in the Linux version
of syslogd(8)). Time stamps have the priority warn,
system-level errors have the priority err, and important
start-up messages the priority alert. The signature key for the
log file will never be logged to syslog or the log file itself.
For failures to verify file integrity, error levels are defined
in the next section.
PrintSeverity=val,
LogSeverity=val,
ExportSeverity=val,
ExternalSeverity=val,
PreludeSeverity=val,
DatabaseSeverity=val, and
SyslogSeverity=val set the thresholds for logging via stdout (or
/dev/console), log file, TCP forwarding, calling external
programs, and syslog(3).
[EventSeverity]
SeverityReadOnly=val,
SeverityLogFiles=val,
SeverityGrowingLogs=val,
SeverityIgnoreNone=val,
SeverityIgnoreAll=val,
SeverityPrelink=val,
SeverityUser0=val,
SeverityUser1=val,
SeverityUser2=val,
SeverityUser3=val, and
SeverityUser4=val define the error levels for failures to verify
the integrity of files/directories of the respective types. I.e.
if such a file shows unexpected modifications, an error of level
val will be generated, and logged to all facilities with a
threshold of at least val.
SeverityFiles=val sets the error level for file access problems,
and
SeverityDirs=val for directory access problems.
SeverityNames=val sets the error level for obscure file names
(e.g. non-printable characters), and for files with invalid
UIDs/GIDs.
[External]
OpenCommand=path Start the definition of an external logging
program|script.
SetType=log|srv Type/purpose of program (log for logging).
SetCommandline=list Command line options.
SetEnviron=KEY=val Environment for external program.
SetChecksum=val Checksum of the external program (checked before
invoking).
SetCredentials=username User as who the program will run.
SetFilterNot=list Words not allowed in message.
SetFilterAnd=list Words required (ALL) in message.
SetFilterOr=list Words required (at least one) in message.
SetDeadtime=seconds Time between consecutive calls.
[Utmp] Configuration for watching login/logout events.
LoginCheckActive=0|1 Switch off/on login/logout reporting.
LoginCheckInterval=val Interval (seconds) between checks for
login/logout events.
SeverityLogin=val
SeverityLoginMulti=val
SeverityLogout=val Severity levels for logins, multiple logins
by same user, and logouts.
[Kernel]
Configuration for detecting kernel rootkits.
KernelCheckActive=0|1 Switch off/on checking of kernel syscalls
to detect kernel module rootkits.
KernelCheckInterval=val Interval (seconds) between checks.
SeverityKernel=val Severity level for clobbered kernel syscalls.
KernelCheckIDT=0|1 Whether to check the interrrupt descriptor
table.
KernelSystemCall=address The address of system_call (grep
system_call System.map). Required after a kernel update.
KernelProcRoot=address The address of proc_root (grep ’
proc_root$’ System.map). Required after a kernel update.
KernelProcRootIops=address The address of
proc_root_inode_operations (grep proc_root_inode_operations
System.map). Required after a kernel update.
KernelProcRootLookup=address The address of proc_root_lookup
(grep proc_root_lookup System.map). Required after a kernel
update.
[SuidCheck]
Settings for finding SUID/SGID files on disk.
SuidCheckActive=0|1 Switch off/on the check.
SuidCheckExclude=path
A directory (and its subdirectories)
to exclude from the check. Only one directory can be specified
this way.
SuidCheckSchedule=schedule Crontab-like schedule for checks.
SeveritySuidCheck=severity Severity for events.
SuidCheckFps=fps Limit files per seconds for SUID check.
SuidCheckNosuid=0|1 Check filesystems mounted as nosuid.
Defaults to not.
SuidCheckQuarantineFiles=0|1 Whether to quarantine files.
Defaults to not.
SuidCheckQuarantineMethod=0|1|2 Quarantine method. Delete = 1,
remove suid/sgid flags = 1, move to quarantine directory = 2.
Defaults to 1 (remove suid/sgid flags).
[Mounts]
Configuration for checking mounts.
MountCheckActive=0|1 Switch off/on this module.
MountCheckInterval=seconds
The interval between checks (default 300).
SeverityMountMissing=severity Severity for reports on missing
mounts.
SeverityOptionMissing=severity Severity for reports on missing
mount options.
CheckMount=path [mount_options]
Mount point to check. Mount options must be given as comma-
separated list, separated by a blank from the preceding mount
point.
[UserFiles]
Configuration for checking paths relative to user home
directories.
UserFilesActive=0|1 Switch off/on this module.
UserFilesName=filename policy
Files to check for under each $HOME. Allowed values for ’policy’
are: allignore, attributes, logfiles, loggrow, noignore
(default), readonly, user0, user1, user2, user3, and user4.
UserFilesCheckUids=uid_list A list of UIDs where we want to
check. The default is all. Ranges (e.g. 100-500) are allowed. If
there is an open range (e.g. 1000-), it must be last in the
list.
[ProcessCheck]
Settings for finding hidden/fake,required processes on the local
host.
ProcessCheckActive=0|1 Switch off/on the check.
ProcessCheckInterval=seconds
The interval between checks (default 300).
SeverityProcessCheck=severity Severity for events (default
crit).
ProcessCheckMinPID=pid The minimum PID to check (default 0).
ProcessCheckMaxPID=pid The maximum PID to check (default 32767).
ProcessCheckPSPath=path The path to ps (autodetected at compile
time).
ProcessCheckPSArg=argument The argument to ps (autodetected at
compile time). Must yield PID in first column.
ProcessCheckExists=regular_expression Check for existence of a
process matching the given regular expression.
[PortCheck]
Settings for checking open ports on the local host.
PortCheckActive=0|1 Switch off/on the check.
PortCheckInterval=seconds
The interval between checks (default 300).
PortCheckUDP=yes|no Whether to check UPD ports as well (default
yes).
SeverityPortCheck=severity Severity for events (default crit).
PortCheckInterface=ip_address Additional interface to check.
PortCheckOptional=ip_address:list Ports that may, but need not
be open. The ip_address is the one of the interface, the list
must be comma or whitespace separated, each item must be
(port|service)/protocol, e.g. 22/tcp,nfs/tcp/nfs/udp.
PortCheckRequired=ip_address:list Ports that are required to be
open. The ip_address is the one of the interface, the list must
be comma or whitespace separated, each item must be
(port|service)/protocol, e.g. 22/tcp,nfs/tcp/nfs/udp.
[Database]
Settings for logging to a database.
SetDBHost=db_host Host where the DB server runs (default:
localhost). Should be a numeric IP address for PostgreSQL.
SetDBName=db_name Name of the database (default: samhain).
SetDBTable=db_table Name of the database table (default: log).
SetDBUser=db_user Connect as this user (default: samhain).
SetDBPassword=db_password Use this password (default: none).
SetDBServerTstamp=true|false Log server timestamp for client
messages (default: true).
UsePersistent=true|false Use a persistent connection (default:
true).
[Misc] Daemon=no|yes Detach from controlling terminal to become a
daemon.
MessageHeader=format Costom format for message header.
Replacements: %F source file name, %L source file line, %S
severity, %T timestamp, %C message class.
VersionString=string Set version string to include in file
signature database (along with hostname and date).
SetReverseLookup=true|false If false, skip reverse lookups when
connecting to a host known by name rather than IP address.
HideSetup=yes|no Don’t log name of config/database files on
startup.
SyslogFacility=facility Set the syslog facility to use. Default
is LOG_AUTHPRIV.
MACType=HASH-TIGER|HMAC-TIGER Set type of message authentication
code (HMAC). Must be identical on client and server.
SetLoopTime=val Defines the interval (in seconds) for
timestamps.
SetConsole=device Set the console device (default /dev/console).
MessageQueueActive=1|0 Whether to use a SysV IPC message queue.
PreludeMapToInfo=listofseverities The severities (see section
[Log]) that should be mapped to impact severity info in prelude.
PreludeMapToLow=listofseverities The severities (see section
[Log]) that should be mapped to impact severity low in prelude.
PreludeMapToMedium=listofseverities The severities (see section
[Log]) that should be mapped to impact severity medium in
prelude.
PreludeMapToHigh=listofseverities The severities (see section
[Log]) that should be mapped to impact severity high in prelude.
SetMailTime=val defines the maximum interval (in seconds)
between succesive e-mail reports. Mail might be empty if there
are no events to report.
SetMailNum=val defines the maximum number of messages that are
stored before e-mailing them. Messages of highest priority are
always sent immediately.
SetMailAddress=username@host sets the recipient address for
mailing. No aliases should be used. For security, you should
prefer a numerical host address.
SetMailRelay=server sets the hostname for the mail relay server
(if you need one). If no relay server is given, mail is sent
directly to the host given in the mail address, otherwise it is
sent to the relay server, who should forward it to the given
address.
SetMailSubject=val defines a custom format for the subject of an
email message.
SetMailSender=val defines the sender for the ’From:’ field of a
message.
SetMailFilterAnd=list defines a list of strings all of which
must match a message, otherwise it will not be mailed.
SetMailFilterOr=list defines a list of strings at least one of
which must match a message, otherwise it will not be mailed.
SetMailFilterNot=list defines a list of strings none of which
should match a message, otherwise it will not be mailed.
SamhainPath=/path/to/binary sets the path to the samhain binary.
If set, samhain will checksum its own binary both on startup and
termination, and compare both.
SetBindAddress=IP_address The IP address (i.e. interface on
multi-interface box) to use for outgoing connections.
SetTimeServer=server sets the hostname for the time server.
TrustedUser=name|uid Add a user to the set of trusted users
(root and the effective user are always trusted. You can add up
to 7 more users).
SetLogfilePath=AUTO|/path Path to logfile (AUTO to tack hostname
on compiled-in path).
SetLockfilePath=AUTO|/path Path to lockfile (AUTO to tack
hostname on compiled-in path).
Standalone or client only
SetNiceLevel=-19..19 Set scheduling priority during file check.
SetIOLimit=bps Set IO limits (kilobytes per second) for file
check.
SetFilecheckTime=val Defines the interval (in seconds) between
succesive file checks.
FileCheckScheduleOne=schedule Crontab-like schedule for file
checks. If used, SetFilecheckTime is ignored.
UseHardlinkCheck=yes|no Compare number of hardlinks to number of
subdirectories for directories.
HardlinkOffset=N:/path Exception (use multiple times for
multiple exceptions). N is offset (actual - expected hardlinks)
for /path.
AddOKChars=N1,N2,.. List of additional acceptable characters
(byte value(s)) for the check for weird filenames. Nn may be hex
(leading ’0x’: 0xNN), octal (leading zero: 0NNN), or decimal.
Use all for all.
FilenamesAreUTF8=yes|no Whether filenames are UTF-8 encoded
(defaults to no). If yes, filenames are checked for invalid
UTF-8 encoding and for ending in invisible characters.
IgnoreAdded=path_regex Ignore if this file/directory is
added/created.
IgnoreMissing=path_regex Ignore if this file/directory is
missing/deleted.
ReportOnlyOnce=yes|no Report only once on a modified file
(default yes).
ReportFullDetail=yes|no Report in full detail on modified files
(not only modified items).
UseLocalTime=yes|no Report file timestamps in local time rather
than GMT (default no). Do not use this with Beltane.
ChecksumTest={init|update|check|none} defines whether to
initialize/update the database or verify files against it. If
’none’, you should supply the required option on the command
line.
SetPrelinkPath=path Path of the prelink executable (default
/usr/sbin/prelink).
SetPrelinkChecksum=checksum TIGER192 checksum of the prelink
executable (no default).
SetLogServer=server sets the hostname for the log server.
SetServerPort=portnumber sets the port on the server to connect
to.
SetDatabasePath=AUTO|/path Path to database (AUTO to tack
hostname on compiled-in path).
DigestAlgo=SHA1|MD5 Use SHA1 or MD5 instead of the TIGER
checksum (default: TIGER192).
RedefReadOnly=+/-XXX,+/-YYY,... Add or subtract tests XXX from
the ReadOnly policy. Tests are: CHK (checksum), TXT (store
literal content), LNK (link), HLN (hardlink), INO (inode), USR
(user), GRP (group), MTM (mtime), ATM (atime), CTM (ctime), SIZ
(size), RDEV (device numbers) and/or MOD (file mode).
RedefAttributes=+/-XXX,+/-YYY,... Add or subtract tests XXX
from the Attributes policy.
RedefLogFiles=+/-XXX,+/-YYY,... Add or subtract tests XXX from
the LogFiles policy.
RedefGrowingLogFiles=+/-XXX,+/-YYY,... Add or subtract tests
XXX from the GrowingLogFiles policy.
RedefIgnoreAll=+/-XXX,+/-YYY,... Add or subtract tests XXX from
the IgnoreAll policy.
RedefIgnoreNone=+/-XXX,+/-YYY,... Add or subtract tests XXX
from the IgnoreNone policy.
RedefUser0=+/-XXX,+/-YYY,... Add or subtract tests XXX from the
User0 policy.
RedefUser1=+/-XXX,+/-YYY,... Add or subtract tests XXX from the
User1 policy.
RedefUser2=+/-XXX,+/-YYY,... Add or subtract tests XXX from the
User2 policy.
RedefUser3=+/-XXX,+/-YYY,... Add or subtract tests XXX from the
User3 policy.
RedefUser4=+/-XXX,+/-YYY,... Add or subtract tests XXX from the
User4 policy.
Server Only
SetUseSocket=yes|no If unset, do not open the command socket.
The default is no.
SetSocketAllowUid=UID Which user can connect to the command
socket. The default is 0 (root).
SetSocketPassword=password Password (max. 14 chars, no ’@’) for
password-based authentication on the command socket (only if the
OS does not support passing credentials via sockets).
SetChrootDir=path If set, chroot to this directory after
startup.
SetStripDomain=yes|no Whether to strip the domain from the
client hostname when logging client messages (default: yes).
SetClientFromAccept=true|false If true, use client address as
known to the communication layer. Else (default) use client name
as claimed by the client, try to verify against the address
known to the communication layer, and accept (with a warning
message) even if this fails.
UseClientSeverity=yes|no Use the severity of client messages.
UseClientClass=yes|no Use the class of client messages.
SetServerPort=number The port that the server should use for
listening (default is 49777).
SetServerInterface=IPaddress The IP address (i.e. interface on
multi-interface box) that the server should use for listening
(default is all). Use INADDR_ANY to reset to all.
SeverityLookup=severity Severity of the message on client
address != socket peer.
UseSeparateLogs=true|false If true, messages from different
clients will be logged to separate log files (the name of the
client will be appended to the name of the main log file to
construct the logfile name).
SetClientTimeLimit=seconds The maximum time between client
messages. If exceeded, a warning will be issued (the default is
86400 sec = 1 day).
SetUDPActive=yes|no yule 1.2.8+: Also listen on 514/udp
(syslog).
[Clients]
This section is only relevant if samhain is run as a log server
for clients running on another (or the same) machine.
Client=hostname@salt@verifier registers a client at host
hostname (fully qualified hostname required) for access to the
log server. Log entries from unregistered clients will not be
accepted. To generate a salt and a valid verifier, use the
command samhain -P password, where password is the password of
the client. A simple utility program samhain_setpwd is provided
to re-set the compiled-in default password of the client
executable to a user-defined value.
[EOF] An optional end marker. Everything below is ignored.
SEE ALSO
samhain(8)
AUTHOR
Rainer Wichmann (http://la-samhna.de)
BUG REPORTS
If you find a bug in samhain, please send electronic mail to
support@la-samhna.de. Please include your operating system and its
revision, the version of samhain, what C compiler you used to compile
it, your ’configure’ options, and anything else you deem helpful.
COPYING PERMISSIONS
Copyright (©) 2000, 2004, 2005 Rainer Wichmann
Permission is granted to make and distribute verbatim copies of this
manual page provided the copyright notice and this permission notice
are preserved on all copies.
Permission is granted to copy and distribute modified versions of this
manual page under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
Jul 29, 2004