samhain file integrity scanner | online documentation

Setting up a client/server samhain system

This document aims to explain how to set up a client/server samhain system, where the client (samhain) runs on one machine to be monitored, and sends reports via TCP/IP to a remote server (yule).

Please note: the server (yule) does not perform any filesystem and/or kernel checks. If you want to perform such checks on the log server host, you need to run a samhain client on this host as well.

Client and server are distict applications, and must be built separately. By default, installation names and paths (e.g. the configuration file) are different. Do not blame us if you abuse './configure' options to cause name clashes, if you install both on the same host.


Samhain can be compiled for remote logging to a central server via a secure (AES-encrypted, signed, and authenticated) TCP/IP connection.

In addition, both the client configuration file and the file signature database can be stored on the server. The client will then pull them from the server upon startup.

This requires three basic steps:

  1. compile and install server and client,
  2. establish trust between client and server, and
  3. enable remote logging in the client's configuration file.


The server - yule

Note: the server can be started with root privileges (e.g. to use a privileged port < 1024), but it will always drop root privileges irrevocably before accepting any connections, and run as a non-root user. This user can be specified explicitely with the configure option --enable-identity=USER. The default is the first existing user out of the list yule, daemon, nobody.

bash$ ./configure --enable-network=server
bash$ make
bash$ make install

The client - samhain

The path after the keyword REQ_FROM_SERVER has the following meaning:

Establishing trust between client and server

By default, samhain uses the SRP (Secure Remote Password) protocol, with a password that is embedded in the client binary, and a corresponding verifier that is in the server configuration file.

Embedding the password in the client, and register it with the server

To embed the password in the binary, there is a dummy password compiled in as placeholder, and a utility samhain_setpwd is provided that

  1. takes a password as input,
  2. searches the original binary for the correct place (i.e. the placeholder), and
  3. writes a copy of the original binary, with the placeholder replaced by the password. The original is left untouched. The copy cannot be changed to another password anymore.

For convenience, the server has functions to


rainer$ ./samhain_setpwd

Usage: samhain_setpwd <filename> <suffix> <new_password>

   This program is a utility that will:
    - search in the binary executable <filename> for samhain's
      compiled-in default password,
    - change it to <new_password>,
    - and output the modified binary to <filename>.<suffix>

   To allow for non-printable chars, <new_password> must be
   a 16-digit hexadecimal number (only 0-9,A-F allowed in input),
   thus corresponding   to an 8-byte password.

   Example: 'samhain_setpwd samhain new 4142434445464748'
   takes the file 'samhain', sets the password to 'ABCDEFGH'
   ('A' = 41 hex, 'B' = 42 hex, ...) and outputs the result
   to ''.

rainer$ yule -G

rainer$ ./samhain_setpwd samhain new 5B5CDF18CE8D66A3
INFO   old password found
INFO   replaced:  f7c312aaaa12c3f7  by:  5b5cdf18ce8d66a3
INFO   finished

rainer$ scp ./
samhain              100% |********************************|   592 KB    00:00

rainer$ yule -P 5B5CDF18CE8D66A3

rainer$ yule -P 5B5CDF18CE8D66A3 | sed >> /etc/yulerc

rainer$ tail -2 /etc/yulerc

rainer$ /etc/init.d/yule reload

Note 1: the verifier must be in the [Clients] section of the server configuration file. It is convenient if this is the last section in the config file, because then you can just concatenate the output of yule -P PASSWORD to the configuration file. This allows for better automatisation with a simple script.

Note 2: samhain comes with a deploy system that handles the deployment of clients, including password embedding and server configuration, in a semi-automatic way. This deploy system is tested and used in a production system of more than 50 machines, and described in detail in Chapt. 10 of the MANUAL.

Enabling remote logging

Samhain has multiple independent logging facilities (such as a local logfile, syslog, e-mail, TCP/IP, etc.) that can be used in parallel. You therefore have to specify in the client's configuration file, which logging facility you want to use.

Selecting logging facilities is done by setting appropriate thresholds in the [Log] section of the configuration file: each message with a priority exceeding the threshold will be logged via the respective facility. Setting the threshold to none will disable a facility. For details, refer to Chapt. 4 in the MANUAL.


To enable remote logging to the server for all messages of priority error or higher, use the following directive in the client configuration file:


Databases and config files on the server

The client does not tell the server the path to the requested file - it just requests a config or a database file. It's entirely the responsibility of the server to locate the correct file and send it.

The server has a data directory, which by default would be /var/lib/yule, but depends on your compile options.

Config files and baseline databases for clients must be located in this directory, and they must be named as follows:

Configuration files: rc.client.mydomain.tld or simply rc (this can be used as a catchall file).

Database files: file.client.mydomain.tld or simply file (this can be used as a catchall file).