Man Linux: Main Page and Category List


       samhain - check file integrity


       samhain   {  -t  init|--set-checksum-test=init  }  [--init2stdout]  [-r
       DEPTH|--recursion=DEPTH] [log-options]

       samhain { -t  update|--set-checksum-test=update  }  [-D  |  --daemon  |
       --foreground] [--forever] [-r DEPTH|--recursion=DEPTH] [log-options]

       samhain  {  -t  check|--set-checksum-test=check  }  [-D  |  --daemon  |
       --foreground] [--forever] [-r DEPTH,--recursion=DEPTH] [log-options]

       samhain    [-a    |    --full-detail]    [--delimited]     -d     file|

       samhain [-j | --just-list] -L logfile| --verify-log=logfile

       samhain -M mailbox| --verify-mail=mailbox

       samhain --server-port=portnumber

       samhain -H string | --hash-string=string

       samhain -c | --copyright

       samhain -v | --version

       samhain -h | --help

       samhain -V key@/path/to/executable | --add-key=key@/path/to/executable

       yule  [-q  |  --qualified]  [  --chroot=chrootdir]  [-D  |  --daemon  |
       --foreground] [log-options]

       yule [-P password | --password=password]

       yule [-G | --gen-password]

       [-s  threshold  |  --set-syslog-severity=threshold]  [-l  threshold   |
       --set-log-severity=threshold]          [-m          threshold         |
       --set-mail-severity=threshold]         [-e         threshold          |
       --set-export-severity=threshold]         [-p         threshold        |
       --set-print-severity=threshold]         [-x         threshold         |
       --set-external-severity=threshold]  [ --set-prelude-severity=threshold]
       [    --set-database-severity=threshold]     [     --enable-trace]     [


       The  information  in  this  man  page  is  not  always up to date.  The
       authoritative documentation is the user manual.


       samhain is a file integrity  /  intrusion  detection  system  both  for
       single  hosts  and  networks.   It consists of a monitoring application
       (samhain) running on individual hosts, and (optionally) a  central  log
       server  (yule).   Currently,  samhain  can  monitor  the  integrity  of
       files/directories, and (optionally)  also  check  for  kernel  rootkits
       (Linux  and FreeBSD only), search the disk for SUID/SGID, and watch for
       login/logout events.

       samhain/yule can log by email, to a tamper-resistant, signed log  file,
       to  syslog,  to the Prelude IDS, to a MySQL/PostgreSQL/Oracle database,
       and/or to stdout (/dev/console if run as daemon).  samhain/yule can run
       as  a  daemon,  and  can use a time server instead of the host’s system
       clock. Most of the functionality is defined  by  a  configuration  file
       that is read at startup.

       Most  options  of these usually would be set in the configuration file.
       Options  given  on  the  command  line  will  override  those  in   the
       configuration file.

       samhain -t init, --set-checksum-test=init [options]

       Initialize the database of file signatures. The path to the database is
       compiled in, and initializing will append to the  respective  file  (or
       create  it,  if  it does not exist).  It is ok to append to e.g. a JPEG
       image, but it is an  error  to  append  to  an  already  existing  file
       signature database.

              Write the database to stdout.

       [-r DEPTH|--recursion=DEPTH]
              Set the (global) recursion depth.

       samhain -t update, --set-checksum-test=update [options]

       Update  the  database  of  file signatures. The path to the database is
       compiled in, and updating will overwrite the  database,  starting  from
       the  start  of the database (which may not be identical to the start of
       the file - see above).

       [-r DEPTH|--recursion=DEPTH]
              Set the (global) recursion depth.

              Run as daemon. File checks are performed  as  specified  by  the
              timing  options  in  the  configuration  file. Updates are saved
              after each file check.

              Run in the foreground. This will cause samhain to exit after the
              update, unless the option --forever is used.

              If  not  running  as  daemon,  do  not  exit after finishing the
              update, but loop forever, and perform checks with  corresponding
              database   updates  according  to  the  timing  options  in  the
              configuration file.

       samhain -t check, --set-checksum-test=check [options]

       Check the filesystem against the database of file signatures.  The path
       to the database is compiled in.

       [-r DEPTH|--recursion=DEPTH]
              Set the (global) recursion depth.

              Run  as  daemon.  File  checks are performed as specified by the
              timing options in the configuration file.

              Run in the foreground. This will cause samhain to exit after the
              file check, unless the option --forever is used.

              If not running as daemon, do not exit after finishing the check,
              but loop forever, and perform checks  according  to  the  timing
              options in the configuration file.

       samhain     [-a     |    --full-detail]    [--delimited]    -d    file|

       List the entries in the file signature database in a ls -l like format.

       [-a | --full-detail]
              List  all  informations  for each file, not only those you would
              get with ls -l. Must precede the -d option.

              List all  informations  for  each  file,  in  a  comma-separated
              format.  Must precede the -d option.

              List  the  literal  content  of  the given file as stored in the
              database.  Content is not stored by default, must be enabled  in
              the runtime configuration file. Must precede the -d option.

       These  options will only work, if the executable used for verifying the
       audit trail is compiled with the same --enable-base=... option  as  the
       executable of the reporting process.

       samhain [-j | --just-list] -L logfile| --verify-log=logfile

       Verify   the  integrity  of  a  signed  logfile.  The  signing  key  is
       auto-generated on startup, and sent by email.  samhain will ask for the
       key.  Instead  of  entering the key, you can also enter the path to the
       mailbox holding the respective email message.

       [-j | --just-list]
              Just list the logfile, do not verify it. This option  must  come
              first.   It  is  mainly  intended  for listing the content of an
              obfuscated logfile, if samhain  is  compiled  with  the  stealth

              samhain -M mailbox| --verify-mail=mailbox

              Verify  the  integrity  of  the  email reports from samhain. All
              reports must be in the same file.

       samhain --server-port=portnumber

       Choose the port on the server host to which the client will connect.

       samhain -H string | --hash-string=string

       Compute the TIGER192 checksum of a string. If the string starts with  a
       ’/’,  it  is  considered  as  a  pathname,  and  the  checksum  of  the
       corresponding file will be computed.

       samhain -c | --copyright

       Print the copyright statement.

       samhain -v | --version

       Show version and compiled-in options.

       samhain -h | --help

       Print  supported  command  line  options  (depending   on   compilation

       samhain -V key@/path/to/executable | --add-key=key@/path/to/executable

       See the section "SECURITY" below.

       yule  [-q  |  --qualified]  [  --chroot=chrootdir]  [-D  |  --daemon  |
       --foreground] [log-options]

       Start the server, which is named yule by  default.  If  the  server  is
       started with superuser privileges, it will drop them after startup.

       [-q | --qualified]
              Log  client  hostnames with fully qualified path. The default is
              to log only the leftmost domain label (i.e. the hostname).

       [      --chroot=chrootdir]  Chroot  to  the  listed   directory   after

       [-D | --daemon]
              Run as daemon.

              Run in the foreground.

       yule [-G | --gen-password]

       Generate  a  random  8-byte  password  and  print it out in hexadecimal

       yule [-P password | --password=password]

       Use the given password and generate an entry suitable for the [Clients]
       section of the configuration file.

       Depending  on  the compilation options, some logging facilities may not
       be available in your executable.

       -s threshold, --set-syslog-severity=threshold
              Set the threshold for logging events via  syslogd(8).   Possible
              values  are  debug,  info, notice, warn, mark, err, crit, alert,
              and none.   By  default,  everything  equal  to  and  above  the
              threshold  will  be logged.  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.

       -l threshold, --set-log-severity=threshold
              Set the threshold for logging events to the log file.

       -m threshold, --set-mail-severity=threshold
              Set the threshold for logging events via e-mail.

       -e threshold, --set-export-severity=threshold
              Set the threshold for forwarding events via TCP to a log server.

       -x threshold, --set-extern-severity=threshold
              Set the threshold for calling external logging  programs/scripts
              (if any are defined in the configuration file).

       -p threshold, --set-print-severity=threshold
              Set the threshold for logging events to stdout.  If samhain runs
              as a daemon, this is redirected to /dev/console.

              Set the threshold for logging events to the Prelude IDS.

              Set    the    threshold    for    logging    events    to    the
              MySQL/PostgreSQL/Oracle database.


              Switch on/off maximum verbosity for console output.

              Suspend/continue the process, and (on suspend) send a message to
              the server. This message has the same  priority  as  timestamps.
              This  signal allows to run samhain -t init -e none on the client
              to regenerate the database, with download of  the  configuration
              file  from  the  server, while the daemon is suspended (normally
              you would get errors because of concurrent access to the  server
              by two processes from the same host).

       SIGHUP Reread the configuration file.


              Terminate after processing all pending requests from clients.

              Unlock  the  log  file,  pause  for three seconds, then proceed,
              eventually re-locking the log file and starting  a  fresh  audit
              trail on next access.

              Force  a  file check (only client/standalone, and only in daemon


       The database (default name samhain_file) is a binary file, which can be
       created  or  updated using the -t init or the -t update option.  If you
       use -t init, you need to remove the old database first,  otherwise  the
       new  version  will  be appended to the old one.  The file may be (clear
       text) signed by PGP/GnuPG.
       It is recommended to use GnuPG with  the  options  gpg  -a  --clearsign
       samhain will check the signature, if compiled with support for that.

       At  startup  samhain  will  compute  the  checksum of the database, and
       verify it for each further access. This checksum is not stored on  disk
       (i.e.  is lost after program termination), as there is no secure way to
       store it.


       Each entry in the log  file  has  the  format  Severity  :  [Timestamp]
       Message,  where the timestamp may be obtained from a time server rather
       than from the system clock, if samhain has been compiled  with  support
       for  this.  Each entry is followed by a signature, which is computed as
       Hash(Entry Key_N), and Key_N is computed as  Hash(Key_N-1),  i.e.  only
       knowledge of the first signature key in this chain allows to verify the
       integrity of the log file. This first key is autogenerated and e-mailed
       to the designated recipient.

       The  default  name of the log file is samhain_log.  To prevent multiple
       instances of samhain from writing to the same log file, the log file is
       locked  by  creating  a lock file, which is normally deleted at program
       termination.  The default name of the lock file  is  samhain.lock.   If
       samhain  is terminated abnormally, i.e. with kill -9, a stale lock file
       might remain, but usually samhain will be able to  recognize  that  and
       remove the stale lock file on the next startup.


       E-mails are sent (using built-in SMTP code) to one recipient only.  The
       subject line contains timestamp and hostname, which are repeated in the
       message  body.   The  body of the mail contains a line with a signature
       similar to that in the log file, computed from the message and  a  key.
       The key is iterated by a hash chain, and the initial key is revealed in
       the first email sent.  Obviously, you have to believe that  this  first
       e-mail is authentical ...


       To  monitor  several  machines,  and  collecting  data by a central log
       server, samhain may be compiled as a client/server application. The log
       server  (yule)  will accept connection requests from registered clients
       only.  With  each  client,  the  server  will   first   engage   in   a
       challenge/response  protocol  for  authentication  of  the  client  and
       establishing a session key.

       This protocol requires on the client side a password, and on the server
       side a verifier that is computed from the password.

       To register a client, simply do the following:
       First,  with  the  included  utility  program samhain_setpwd re-set the
       compiled-in default password of the client executable to your preferred
       value  (with  no  option, a short usage help is printed).  To allow for
       non-printable chars,  the  new  value  must  be  given  as  a  16-digit
       hexadecimal  string (only 0123456789ABCDEF in string), corresponding to
       an 8-byte password.
       Second, after re-setting the password in the client executable, you can
       use  the  server’s convenience function yule -P password that will take
       as  input  the  (16-digit  hex)  password,  compute  the  corresponding
       verifier,  and  outputs  a default configuration file entry to register
       the client.
       Third, in the configuration file for the server,  under  the  [Clients]
       section,   enter   the   suggested   registration  entry  of  the  form
       Client=hostname@salt@verifier,  where  hostname  must  be  the   (fully
       qualified) hostname of the machine on which the client will run.  Dont
       forget to reload the server configuration thereafter.

       If a connection attempt is made, the server will lookup the  entry  for
       the  connecting  host, and use the corresponding value for the verifier
       to engage in the session key exchange. Failure to verify  the  client’s
       response(s) will result in aborting the connection.


       samhain  may  be compiled with support for a stealth mode of operation,
       meaning that the program can be run without any obvious  trace  of  its
       presence  on  disk.  The supplied facilities are simple - they are more
       sophisticated than just running the program under a different name, and
       might  thwart efforts using ’standard’ Unix commands, but they will not
       resist a search using dedicated utilities.

       In this mode, the runtime executable will hold  no  printable  strings,
       and  the  configuration  file  is expected to be a postscript file with
       uncompressed image data, wherein the configuration data are  hidden  by
       steganography.   To  create such a file from an existing image, you may
       use e.g.  the program convert(1), which is part of  the  ImageMagick(1)
       package, such as: convert +compress ima.jpg

       To hide/extract the configuration data within/from the postscript file,
       a utility program samhain_stealth is provided.  Use it without  options
       to get help.

       Database  and  log file may be e.g. existing image files, to which data
       are appended, xor’ed with some constant to mask them as binary data.

       The  user  is  responsible  by  herself  for  re-naming  the   compiled
       executable(s)  to  unsuspicious  names,  and choosing (at compile time)
       likewise unsuspicious names for config file, database, and log  (+lock)


       For  security  reasons,  samhain  will not write log or data files in a
       directory, remove the lock file, or read the configuration file, if any
       element  in  the  path  is  owned  or  writeable  by  an untrusted user
       (including group-writeable files with untrusted users in the group, and
       world-writeable files).
       root  and the effective user are always trusted. You can add more users
       in the configuration file.

       Using a numerical host address in the e-mail  address  is  more  secure
       than using the hostname (does not require DNS lookup).

       If  you  use  a  precompiled  samhain  executable  (e.g.  from a binary
       distribution), in principle a prospective intruder could easily  obtain
       a  copy  of  the executable and analyze it in advance. This will enable
       her/him to generate fake audit trails and/or generate a trojan for this
       particular binary distribution.
       For  this  reason, it is possible for the user to add more key material
       into the binary executable. This is done with the command:

       samhain --add-key=key@/path/to/executable

       This will read the file /path/to/executable, add  the  key  key,  which
       should  not contain a ’@’ (because it has a special meaning, separating
       key from path), overwrite any key previously set by this  command,  and
       write the new binary to the location /path/to/executable.out (i.e. with
       .out appended). You should then copy the new binary to the location  of
       the old one (i.e. overwrite the old one).

       Note  that using a precompiled samhain executable from a binary package
       distribution is not recommended unless  you  add  in  key  material  as
       described here.


       For initializing the key(s), /dev/random is used, if available. This is
       a device supplying cryptographically strong (non-deterministic)  random
       noise.  Because  it  is  slow, samhain might appear to hang at startup.
       Doing some random things  (performing  rain  dances,  spilling  coffee,
       hunting  the  mouse)  might  speed  up  things.  If  you  do  not  have
       /dev/random, lots of statistics from vmstat(8) and  the  like  will  be
       pooled and mixed by a hash function.

       Some  hosts  might  check whether the sender of the mail is valid.  Use
       only login names for the sender.
       For sending mails, you may need to set a  relay  host  for  the  sender
       domain in the configuration file.


       Whoever has the original signature key may change the log file and send
       fake e-mails. The signature keys are e-mailed at program startup with a
       one-time  pad  encryption.  This should be safe against an eavesdropper
       on the network, but not against someone with read access to the binary,
       if she has caught the e-mail.






       Rainer Wichmann (


       If  you  find  a  bug  in  samhain,  please  send  electronic  mail  to  Please include your  operating  system  and  its
       revision,  the  version of samhain, what C compiler you used to compile
       it, your  ’configure’  options,  and  any  information  that  you  deem


       Copyright (©) 1999, 2004 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.

                                07 August 2004