Installing Beltane

System Requirements

Beltane requires

Usage Requirements

In order to make use of Beltane, you need a working installation of the samhain version 1.6.1 or higher file integrity / intrusion detection system.

Your installation of samhain must be configured as client/server system, with file signature databases and client configuration files stored on the central server, and with logging to a MySQL or PostgreSQL database enabled. (For step-by-step instructions to setup samhain, see the Section called Samhain configuration>).

Beltane must be installed on the central log server.

If you are using the stealth option for your samhain installation, the value of XOR_VAL must be the same for all clients.

Configure

To configure Beltane for installation, run the ./configure shell script in the source directory. ./configure takes the following arguments:

Installation

Obviously, Beltanes functionality requires read/write access to the log servers data directory and the files therein. There are some different ways to accomplish this, with respective security implications. Please read the Section called Data access> carefully, and make your own decision.

TipTIP
 

You will need to run Beltane under the same GID as yule in order to have access to the server status (i.e. the server's PID file and the server's HTML status page). If you are using PHP as apache module, you would need to put the webserver in the same group as yule. Otherwise, if you use PHP in CGI mode with the suexec wrapper, you need to put the Beltane user in the same group as yule.

Beltane will work without this, but you will not have access to the server status.

To install, use make && make install.

Next, point your browser to the index.html file in the php-dir where you have installed Beltane, login with the default user/password rainer/wichmann, click on Configure in the main menu (upper left), and change user and password.

You may also need to change the defaults for access to the SQL database (like username, password, database name, table name).

WarningCAVEAT
 

Beltane will require both SELECT and UPDATE privileges to the SQL database. The default SQL database init script for yule (from the samhain tarball) may not set UPDATE privileges for anyone. You are advised to review the SQL permissions, otherwise Beltane will not work properly.

You may or may not want to create a separate user for Beltane (the log server does not require UPDATE privileges, thus can access the SQL database as a less privileged user).

Upgrading

If you are upgrading from a previous version of Beltane, after login you should first click on Configure in the main menu (upper left), and check for new configuration options that may need to be configured correctly.

New in version 0.3: pid_file (the path to the pid file of yule,the log server, and html_file (the path to the HTML status file of yule).

New in version 0.4: n_messages (the maximum number of messages to display, use 0 to display all).

Security

Data access

To update the file signature databases of clients stored on the server, Beltane requires read and write permission for these files, and for the directory within that they reside.

TipTip
 

The server (i.e. Yule) only needs read access to this directory and the files therein. This allows to chown the data directory to another user, as long as Yule has read access (note that due to a bug, as of yule 1.7.7 only the primary group will be considered for read access).

TipTip
 

Writing to the data directory is not performed by the beltane PHP process, but by helper programs (beltane_cp, and beltane_update). This allows to perform write access not with the privileges of the PHP process, but with the privileges of some other user (by making these helper programs SUID 'user', where 'user' should not be 'root').

The PHP process still needs read access for the 'undo' function.

The recommended setup would be as follows:

Note that the data directory must be readable for the PHP process. You may want to include Apache in the samhain group, if you don't use suexec.

Backups

Beltane uses two C programs beltane_cp and beltane_update to perform actions that require write permission to data in the yule data directory. Both can only be used by root and optionally by a single other user (see the Section called Configure>.

beltane_cp will copy a temporary file to the location of the database of installed clients. This database is a flat file in XML format, named yulerc.install.db, and located in the profiles/ subdirectory of the yule data directory. All calls to beltane_cp are logged in the Beltane log file. Upon first access, a backup is created with the extension .old. On further accesses, another backup is created with the extension .bak, that is overwritten if it is older than one day.

beltane_update will update client file signature databases according to its command line arguments. All calls to beltane_update are logged in the Beltane log file. Upon first access, a backup is created with the extension .old. On further accesses, another backup is created with the extension .bak, that is overwritten if it is older than one day. In addition, for each file signature database an inverse log with the extension .log will be written. This inverse log contains for each action the required command to undo that action (plus a comment with the original command). Thus, to undo the last 5 changes on (e.g.) file.client.mydomain.com, you could do:
bash$ tail -10 file.client.mydomain.com.log | tac | /bin/sh 

For the last action, an inverse log with the extension .log.last is written, which is used in the undo option that is displayed after performing an update.

Samhain configuration

To install a samhain/yule client/server system, you may proceed as follows (this looks a bit involved, but much of it, e.g. server installation and SQL database preparation, is only required the first time):

      # build the server (with PostgreSQL support)
      
      $ ./configure --enable-xml-log --with-database=postgresql \
       --enable-network=server
      $ make
      $ make install && make install-boot
      
      # build the client (support fetching database/config from server)
      
      $ ./configure --enable-xml-log --enable-network=client \
       --with-data-file=REQ_FROM_SERVER/var/lib/samhain/samhain_file \
       --with-config-file=REQ_FROM_SERVER/etc/samhainrc \
       --with-logserver=server.yourdomain.com
      $ make
      
      # - Create a password (16 digits hexadecimal, i.e. 0…F),
      # - Register the client with the server
      # - Set password in client, install the client, init database
      
      $ SHPW=`yule -G`
      
      $ yule -P $SHPW | \
       sed s%HOSTNAME%client.yourdomain.com% \
       >> /etc/yulerc
      
      $ ./samhain_setpwd samhain new $SHPW
      $ mv samhain.new samhain
      $ make install && make install-boot
      $ samhain -t init

Now, edit /etc/samhainrc and enable logging to the server by setting an appropriate logging threshold:

[Log]
ExportSeverity=warn

Next, copy the client configuration file and the database of file signatures to the server:

      $ scp /etc/samhainrc root@server.yourdomain.com:/var/lib/yule/rc.client.yourdomain.com
      $ scp /var/lib/samhain/samhain_file root@server.yourdomain.com:/var/lib/yule/file.client.yourdomain.com

On the log server, create the database and use the init script provided in the source directory to create the table:

WarningCAVEAT
 

The PostgreSQL init script will grant insert permission without password to a user 'samhain'. The MySQL init script will not set any permissions. You may want to read the MySQL/PostgreSQL docs and review the permission setup. It is recommended to set a password, and allow connections only from localhost.

      $ su postgres
      $ createdb samhain
      $ createuser samhain
      $ psql -d samhain < samhain.postgres.init
      $ exit

… and edit the server configuration file /etc/yulerc to enable SQL logging:

      [Log]
      DatabaseSeverity=warn

      [Database]
      setdbname=samhain
      setdbtable=log
      setdbuser=samhain

Now you can start yule, the server, and thereafter on the client machine samhain, the client:

      $ /etc/init.d/yule start
      $ /etc/init.d/samhain start