SAMHAINRC(5)

📦 version 4.1.4, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

✨ NAME ✨

samhainrc — the configuration file for samhain(8), bestie. 💅

🚨 WARNING 🚨

okay so real talk: the information in this man page is not always up to date. The authoritative documentation is the user manual. So if something looks sus, check the user manual. No cap. 📖

🌸 DESCRIPTION 🌸

The configuration file for samhain(8) is named samhainrc and it lives 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. 🎨

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.
  • 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. 👋

💖 [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). 💾
  • Daemon=no|yes — want it to ✨detach✨ from the controlling terminal and go full daemon mode? that's this. otherwise it stays attached like a clingy bestie 💅
  • MessageHeader=format — custom format for the message header, make it yours 🎀 the replacement tokens are: %F source file name, %L source file line, %S severity, %T timestamp, %C message class.
  • VersionString=string — set a version string to shove into the file signature database (it goes in alongside the hostname and the date) 🌸
  • SetReverseLookup=true|false — if false, skip reverse lookups when connecting to a host that's known by name instead of by IP address.
  • HideSetup=yes|no — don't log the name of the config/database files on startup. stealth mode, lowkey 🤫
  • SyslogFacility=facility — set which syslog facility to use. default is LOG_AUTHPRIV.
  • MACType=HASH-TIGER|HMAC-TIGER — set the type of message authentication code (HMAC). ⚠️ has to be identical on client and server, no exceptions, periodt.
  • StartupLoadDelay=val — how many seconds to wait after startup before loading the database from the server. default is no wait at all.
  • SetLoopTime=val — the interval (in seconds) for timestamps.
  • SetConsole=device — set the console device (default is /dev/console).
  • MessageQueueActive=1|0 — whether to use a SysV IPC message queue or not.
  • PreludeMapToInfo=listofseverities — which severities (peep the [Log] section for those) get mapped to impact severity info in prelude.
  • PreludeMapToLow=listofseverities — same deal, but the ones mapped to impact severity low in prelude.
  • PreludeMapToMedium=listofseverities — severities mapped to impact severity medium in prelude.
  • PreludeMapToHigh=listofseverities — severities mapped to impact severity high in prelude.
  • SetMailTime=val — the max interval (in seconds) between successive e-mail reports. ngl the mail might be totally empty if there's nothing to report 🙈
  • SetMailNum=val — the max number of messages that get stored up before they're e-mailed out. highest-priority messages always go out immediately though, no queueing, they're the main characters 👑
  • SetMailAddress=username@host — sets the recipient address for mailing. no aliases, bestie. and for security you should really prefer a numerical host address 🔥
  • SetMailRelay=server — sets the hostname for the mail relay server (if you even need one). if no relay server is given, mail goes straight to the host in the mail address; otherwise it goes to the relay server, who's supposed to forward it to the given address.
  • SetMailSubject=val — defines a custom format for the subject line of an email message ✉️
  • SetMailSender=val — defines the sender for the 'From:' field of a message.
  • SetMailFilterAnd=list — a list of strings where all of them have to match a message, or it does not get mailed.
  • SetMailFilterOr=list — a list of strings where at least one has to match a message, or it does not get mailed.
  • SetMailFilterNot=list — a list of strings where none of them should match a message, or it does not get mailed.
  • SamhainPath=/path/to/binary — sets the path to the samhain binary. if you set this, samhain will checksum its own binary both on startup and on termination, then compare the two 👀
  • SetBindAddress=IP_address — the IP address (i.e. the interface on a 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, and you can add up to 7 more users.
  • SetLogfilePath=AUTO|/path — path to the logfile (AUTO tacks the hostname onto the compiled-in path).
  • SetLockfilePath=AUTO|/path — path to the lockfile (AUTO tacks the hostname onto the compiled-in path).

Standalone or client only

  • SetNiceLevel=-19..19 — set the scheduling priority during file check.
  • SetIOLimit=bps — set IO limits (kilobytes per second) for the file check.
  • SetFilecheckTime=val — the interval (in seconds) between successive file checks.
  • FileCheckScheduleOne=schedule — a crontab-like schedule for file checks. if you use this, SetFilecheckTime is ignored, sorry bestie it's one or the other 💀
  • UseHardlinkCheck=yes|no — compare the number of hardlinks to the number of subdirectories for directories.
  • HardlinkOffset=N:/path — an exception (use it multiple times for multiple exceptions). N is the offset (actual minus expected hardlinks) for /path.
  • AddOKChars=N1,N2,.. — list of additional acceptable characters (byte value(s)) for the check for weird filenames. each Nn may be hex (leading '0x': 0xNN), octal (leading zero: 0NNN), or decimal. use all for all of them 🦋
  • FilenamesAreUTF8=yes|no — whether filenames are UTF-8 encoded (defaults to no). if yes, filenames get checked for invalid UTF-8 encoding and for ending in invisible characters 👻
  • IgnoreAdded=path_regex — ignore it if this file/directory is added/created.
  • IgnoreMissing=path_regex — ignore it if this file/directory is missing/deleted.
  • ReportOnlyOnce=yes|no — report only once on a modified file (default is yes).
  • ReportFullDetail=yes|no — report in full detail on modified files, not just the modified items.
  • UseLocalTime=yes|no — report file timestamps in local time rather than GMT (default is 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 it's '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 the database (AUTO tacks the hostname onto the compiled-in path).
  • DigestAlgo=SHA1|MD5 — use SHA1 or MD5 instead of the TIGER checksum (default is TIGER192).
  • RedefReadOnly=+/-XXX,+/-YYY,... — add or subtract tests XXX from the ReadOnly policy. the 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). okay that's a lot but you got this 💪
  • 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, don't 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 doesn't 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 is yes).
  • SetClientFromAccept=true|false — if true, use the client address as known to the communication layer. otherwise (the default) use the client name as claimed by the client, try to verify it against the address known to the communication layer, and accept it anyway — with a warning message — even if that verification fails 🙃
  • UseClientSeverity=yes|no — use the severity of client messages.
  • UseClientClass=yes|no — use the class of client messages.
  • SetServerPort=number — the port the server should use for listening (default is 49777).
  • SetServerInterface=IPaddress — the IP address (i.e. the interface on a multi-interface box) the server should use for listening (default is all). use INADDR_ANY to reset it back to all.
  • SeverityLookup=severity — the severity of the message when the client address is not equal to the socket peer.
  • UseSeparateLogs=true|false — if true, messages from different clients get logged to separate log files (the client's name gets appended to the name of the main log file to build the logfile name) 🗂️
  • SetClientTimeLimit=seconds — the maximum time between client messages. if it's exceeded, a warning gets issued (the default is 86400 sec = 1 day).
  • SetUDPActive=yes|no — yule 1.2.8+: also listen on 514/udp (syslog).

[Clients]

this section only matters if samhain is running as a log server for clients on another machine (or literally the same one, we don't judge 🫶).

  • Client=hostname@salt@verifier — registers a client at host hostname (fully qualified hostname required, don't skimp) for access to the log server. log entries from unregistered clients will not be accepted, no cap 🚫

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 it is ignored ✨ (a whole vibe)

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 💖

okay so bestie, before you go running off to copy this page — there are rules, and they're actually super chill, but we respect them fr fr.

Copyright (©) 2000, 2004, 2005 Rainer Wichmann 👑

Permission is granted to make and distribute verbatim copies of this manual page, as long as the copyright notice and this permission notice stay preserved on all copies. like, don't go deleting them, that's the whole deal. 🫶

Permission is granted to copy and distribute modified versions of this manual page under the same conditions as verbatim copying — provided that the entire resulting derived work gets distributed under the terms of a permission notice identical to this one. so you can remix it, slay, but the permissions notice has to travel with it, unchanged. no cap. ✨

tl;dr — copy it, remix it, share it, but keep the copyright notice and the permission notice intact, and any modified version ships with a notice identical to this one. that's it, that's the vibe check. 🌸

and that's the whole page, bestie — you made it to the end 🎀🦋 this one's from Jul 29, 2004, filed under SAMHAINRC(5). go forth and configure responsibly 💅⭐

📦 where this page comes from