2. Installing Beltane

2.1. System Requirements

Beltanerequires

  • an ANSI C compiler (like gcc),

  • a webserver (tested with apache 1.3.26and apache 2.0.53), and

  • PHP 4.3or later, compiled either as apachemodule, or as CGI program. Your PHP4must have support for:

    • XML parser functions,

    • POSIX funtions (note that on SLES 10, these are in a seperate 'php-posix' rpm), and

    • either MySQL, PostgreSQL, or Oracle, depending on which database you are using.

    [Caution]Warning

    Depending on whether PHP is used as CGI program or as apachemodule, Beltanemust be built with different options for the ./configurescript. The relevant options are: --with-php-dir= DIR, --with-php-extension= EXT, --enable-mod-php, --with-user= USERNAME, and --with-user-home= HOMEDIR. See Section 2.3, “Configure”for details.

2.2. Usage Requirements

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

Your installation of samhainmust 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, PostgreSQL, or Oracledatabase enabled. (For step-by-step instructions to setup samhain, see Section 2.10, “Samhain configuration”).

Beltanemust be installed on the central log server. This is required for filesystem access to the baseline databases stored on the log server.

If you are using the stealth (or micro-stealth) option for your samhaininstallation, the value of XOR_VALmust be the same for all clients.

2.3. Configure

[Tip]TIP

Obviously, Beltanesfunctionality 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 Section 2.8.4, “Data access”carefully, and make your own decision.

To configure Beltanefor installation, run the ./configureshell script in the source directory. ./configuretakes the following arguments:

  • --with-php-dir= DIR— This is the directory to which the files are installed that are interpreted by PHP. If PHP is installed as a CGI program, you should allow execution of CGI programs for that directory in your webserver configuration. For apache, you need something like (if DIRis /var/www/beltane):

    <Directory /var/www/beltane>
        AllowOverride None
        Options +ExecCGI -Includes
    </Directory>
    
    <IfModule mod_mime.c>
        AddHandler cgi-script .cgi
    </IfModule>
                
  • --with-php-extension= EXT— This is the file extension for files that are interpreted by PHP. If PHP is installed as a CGI program, the extension should probably be cgi(see the AddHandlerin the apacheconfiguration file), else phpor maybe ph4. If you use PHP as apachemodule, the extension for php files is given in the apacheconfiguration file via the directive:

    	    AddType application/x-httpd-php .php
              

  • --enable-mod-php— Use this if your PHP is compiled as apachemodule.

  • --with-user-home= HOMEDIR— The directory to use for the configuration file, by default the home directory of the user defined with the option --with-user= USERNAMEbecause that user needs to have read/write acces to this directory. You may want to make sure that this directory is outside the webserver root such that its content will not be served by the webserver.

  • --with-user= USERNAME— The username of the user that is allowed to use the beltane_cp, beltane_update, beltane_sign, and beltane_logcommands. If PHP is compiled as apachemodule, this must be the user as that the web server runs. Else, if PHP is compiled as CGI program, and you are using the suexecwrapper, this must be the user as that the PHP scripts are executed. This is discussed in more details in Section 2.8, “Security”.

    [Caution]Warning

    Some files required by Beltane(see Section 10, “Files and directories”will be chowned/chgrp'd to that user upon installation. Failure to choose the correct user will result in startup errors due to inaccessible files.

  • --with-data-dir= DIR— This is the data directory of the server, where client file signature databases and configuration files are stored. It is the same directory that is defined with --with-data-dir= DIRin the samhainconfiguration. The default is /var/lib/yule.

  • --with-logfile= FILE— This is the location of the global log file written by Beltane, where all calls to beltane_cpand beltane_updateare logged. The default is /var/log/beltane_update_log.

  • --enable-stealth= XOR_VAL— If you are using the stealth (or micro-stealth) option for your samhaininstallation, you need to provide the XOR_VALwith this option, otherwise Beltanewill not be able to handle the file signature databases.

    [Caution]Warning

    Whenever you have compiled your samhain clients with either --enable-stealth= XOR_VALor --enable-micro-stealth= XOR_VAL, you need this option. The value provided for XOR_VAL must be the same as for the clients, and thus also must be identical for all clients.

  • --disable-backupsBeltanecreates backups of updated databases. This, however, results in a doubling of diskspace required. Use this option to disable this feature.

2.4. Installation

To install, use make && make install.

2.5. Fixing filesystem access permissions

[Tip]Do not blindly follow the example below

There are plenty of ways to install yule (the samhain server) and beltane, so here we just discuss an example. However, this should give you an idea what to fix if things do not work. DO NOT blindly follow this example without thinking first.

In particular, we assume: PHP is php_mod (not cgi), users 'www' (webserver), 'beltane', and 'yule' (samhain server) exist, and beltane and yule are in group 'samhain'. Beltane helper applications will be set SUID/SGID beltane/samhain, and the Yule directory layout is LSB (Linux standard base), which is the default.

See also Section 2.8.4, “Data access”for some more information.

Webserver access to beltane

You may need to tell the web server where Beltane is located. E.g. for Apache, you may want to include the following in your site configuration:

Alias /beltane "/var/www/beltane"
<Directory "/var/www/beltane">
  Options Indexes
  AllowOverride None
  Order allow,deny
  Allow from all
</Directory>
	    

As you have installed the beltane PHP scripts into some directory DIR (configure option --with-php-dir= DIR), you should make sure that the webserver has read accessto this directory and everything below it

              bash$ chown -R root DIR
              bash$ chmod -R 555  DIR
            
Access to the yule data directory for user beltane

For security, we do not give the webserver access to the data directory, but transfer privileges by making the beltane helper applications SUID/SGID beltane/samhain. Accordingly, user 'beltane' needs read/write access, and group 'samhain' (yule) needs read access.

              bash$ chown beltane:samhain /var/lib/yule
              bash$ chown beltane:samhain /var/lib/yule/rc.*
              bash$ chown beltane:samhain /var/lib/yule/file.*
            
Access to the yule HTML status file

This file is only re-written by yule, so yule will not change the permissions. It needs to be readable from PHP (i.e. for user 'www' in our example).

              bash$ chmod 644 /var/log/yule/yule.html
            
Public and secret PGP keys for signing

If you are using signed configuration and database files, the user 'beltane' needs access to the keys. Signing is done using the helper application beltane_sign, which is SUID/SGID beltane/samhain in our example. With this example, you would then configure 'GPG Homedir' to DIR/.gnupg in the Beltane configuration screen.

              bash$ cp -r ~/.gnupg DIR/
              bash$ chown -R beltane:samhain DIR/.gnupg
            
Access to the database of installed clients

This is the XML format database of installed clients. It can be created through the beltane interface, but if you are using the samhain deployment system, it is created and maintained automatically by that system.

              bash$ chown beltane /var/lib/yule/profiles
              bash$ chmod 755 /var/lib/yule/profiles
              bash$ chown www:samhain \
              /var/lib/yule/profiles/yulerc.install.db
              bash$ chmod 660 \
              /var/lib/yule/profiles/yulerc.install.db
            
Set helper applications SUID/SGID beltane/samhain

                bash$ chown beltane:samhain /usr/local/bin/beltane_*
                bash$ chmod 6755 /usr/local/bin/beltane_*
              

Ownership of log directory

With --with-logfile= LOGDIR/FILEyou can set an appropriate path at compile time.

              bash$ chown beltane:samhain LOGDIR
            
Access to the yulectl utility

This utility is installed with mode 700 by default, but can be set 755 without security implications. You need it if you want to ask clients to reload their configurations via the web interface, or if you want to perform on-demand file integrity checks.

	      bash$ chmod 755 /usr/local/sbin/yulectl
            

The 'yulectl' utility is just an interface to a UNIX domain socket opened by the yule server. It will not work if (1) the server does not open the socket, or (2) authenticating to the server does not succeed. In turn:

(1) in the [Misc] section of the yule configuration, set 'SetUseSocket = True'

(2a) if your operating system supports passing credentials over a socket (Linux and *BSD do), set 'SetSocketAllowUid=UID', where UID is the one of user 'www'.

(2b) if your operating system does NOT support passing credentials over a socket, set 'SetSocketPassword = PASSWORD' (choose any password you like), and create a file .yulectl_credin the HOME directory of the user 'www'. This file must contain a single line with only the PASSWORD. It must be readable for user 'www'.

[Tip]Which authentication method is supported on your OS?

If you run yule -v, yule will tell you whether authentication by UID or by password is required.

2.6. Postinstallation configuration

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

It is perfectly normal if you see a bunch of error messages about access to the database — beltane does not know yet how to access the database, you have to configure that first.

Click on Configurein the main menu (upper panel), 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).

[Caution]CAVEAT

Beltanewill 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 Beltanewill not work properly.

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

2.7. Upgrading

[Tip]Database scheme change for samhain 4.0.0+

As of version 4.0, Samhain optionally logs the checking policy for a file if the option ReportCheckflags is set in the configuration file. If you enable this option, you need to update your database scheme as follows:

Mysql:

	ALTER TABLE samhain.log ADD COLUMN checkflags_old BIGINT UNSIGNED;
	ALTER TABLE samhain.log ADD COLUMN checkflags_new BIGINT UNSIGNED;
      

PostgreSQL:

	ALTER TABLE samhain.log ADD COLUMN checkflags_old NUMERIC(20); 
	ALTER TABLE samhain.log ADD COLUMN checkflags_new NUMERIC(20);
      

Oracle:

	ALTER TABLE samhain.log ADD checkflags_old NUMBER(20); 
	ALTER TABLE samhain.log ADD checkflags_new NUMBER(20); 
      
[Tip]Upgrade to version 2.4.0 of Beltane II

As of version 2.4.0, regular expressions for message filters are Perl Compatible Regular Expressions (PCRE) instead of POSIX regular expressions (rationale: POSIX regex functions are deprecated as of PHP 5.3) Please note that PCRE regular expressions must be enclosed by matching delimiters. Since the closing delimiter can be followed by qualifiers (e.g. /pattern/i for case-insensitive evaluation of 'pattern'), this cannot be upgraded automatically.

[Tip]Database scheme change for samhain 2.8.0+

As of version 2.8.0, Samhain supports IPv6 now, which means that the size of the 'ip' column in the database must be increased from VARCHAR(16) to VARCHAR(46).

Mysql:

 
          ALTER TABLE samhain.log MODIFY ip VARCHAR(46);
	

PostgreSQL:

 
          ALTER TABLE samhain.log ALTER COLUMN ip TYPE VARCHAR(46);
	

Oracle:

 
          ALTER TABLE samhain.log MODIFY ip VARCHAR(46);
	
[Tip]Database scheme change for samhain 2.4.4+

As of version 2.4.4 of Samhain, it is possible now to store the full content of small files in the baseline database. To support this feature with logging to an RDBMS, the DB schema for Oracle needs to be adjusted by converting the link_old, link_new columns from VARCHAR2 to CLOB:

Oracle (MySql, PostgreSQL not affected):

      
	ALTER TABLE samhain.log ADD tmp_name CLOB;
	UPDATE samhain.log SET tmp_name=link_old;
	ALTER TABLE samhain.log DROP COLUMN link_old;
	ALTER TABLE samhain.log RENAME COLUMN tmp_name to link_old;
	  
	ALTER TABLE samhain.log ADD tmp_name CLOB;
	UPDATE samhain.log SET tmp_name=link_new;
	ALTER TABLE samhain.log DROP COLUMN link_new;
	ALTER TABLE samhain.log RENAME COLUMN tmp_name to link_new;
      
[Tip]Database scheme change for samhain 2.3.0+

Version 2.3 of Samhain supports checking of SELinux attributes and/or Posix ACLs. For backward compatibility, this is off by default. If you upgrade Samhain and enable this option, you need to update the database scheme as follows:

Mysql:

 
        ALTER TABLE samhain.log ADD COLUMN acl_old BLOB;
        ALTER TABLE samhain.log ADD COLUMN acl_new BLOB;
      

PostgreSQL:

 
        ALTER TABLE samhain.log ADD COLUMN acl_old TEXT;
        ALTER TABLE samhain.log ADD COLUMN acl_new TEXT;
      

Oracle:

 
        ALTER TABLE samhain.log ADD acl_old VARCHAR2(4000);
        ALTER TABLE samhain.log ADD acl_new VARCHAR2(4000);
	DROP TRIGGER trigger_on_log;
      

If you are upgrading from a previous version of Beltane, after login you should first click on Configure in the main menu (upper panel), 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).

New in version 2.0: Filter messages(POSIX regular expression; matching messages will not be displayed, and optionally their status will be set to 'acknowledged').

View server messages(boolean option; if TRUE, messages from yule, the log server, will also be displayed).

Sort clients by name(boolean option; if TRUE, clients will be sorted alphabetically rather than by highest severity of new messages).

Additional userscan be defined

GPG signing of file signature databases

New in version 2.0.2: Multiplefilters can be defined.

New in version 2.0.4: Reloadcommands for clients can be submitted to the yuleserver.

Editing of client configuration filesis possible

Bulk Updatehas been modified for improved speed

New in version 2.0.13: The file list for bulk updatesmay include checksums.

New in version 2.1.0: New user interface. Manually selecting for update will automatically create a corresponding file list.

New in version 2.1.1: Works with Oracle now. Client editing adapted to deploy.sh version 2.

New in version 2.1.2: Search function for database. New configuration item 'Comment updates' (boolean) to select whether to store update info in the database. User is logged for updates.

New in version 2.2.0: Revised filter options, and more configurable interface.

New in version 2.3.0: Hosts and users can be divided into groups. LDAP authentication or browser-based login is possible if HTTPS is used for the connection to beltane. Comments for updates are enforced if comments are enabled.

New in version 2.3.4: User can set their own preferences, filters, GPG key, and password. Multiple admins are possible.

New in version 2.3.7: If file contents are stored, it's possible to view a diff for reported modifications.

New in version 2.3.9: It's possible to request an on-demand file system check for clients.

New in version 2.3.20: Enhance search function to diff filesystem changes for clients.

New in version 2.4.0: Replaced POSIX regular expressions (filters, host and path in bulk update) with Perl Compatible Regular Expressions (PCRE) since the PHP POSIX regex functions are deprecated as of PHP 5.3. Enhance search function to search for file renames.

New in version 2.5.0: beltane_update command line option to merge databases.

2.8. Security

2.8.1. mod_php vs. CGI PHP

If you have untrusted users which can create their own php scripts, mod_php is not secure, since every php script runs under the same UID (the one of the webserver). Either install CGI PHP and use the Apache suexec wrapper to execute each users' scripts under the user UID, or use a dedicated server for Beltanewith no untrusted users.

2.8.2. Login

Beltaneuses a challenge-response protocol for authentication. To login, the client browser receives a nonce, and sends back the MD5 hash MD5(username MD5(password) nonce). If there is no user action within some timeout interval (by default 600 sec), the user is logged out automatically.

The default login is user/pass = rainer/wichmann. You may want to change this as soon as possible, using the configure option in the menu panel(the upper panel).

You can also use the makepasswd.plPerl script (which is included in the Beltanesource tarfile) to compute an MD5 password hash and insert it manually in the beltanercfile: makepasswd.pl password

2.8.3. SQL Access

Beltanecan be used to acknowledge messages in the database, i.e. note that you have checked the message. This requires update privileges for the database.

You can set the SQL database user and password in the configuration file of Beltane. It is recommended to have one user with select and insert privileges for yule (the samhain log server), and another user with select and update privileges for Beltane.

2.8.4. Data access

To update the file signature databases of clients stored on the server, Beltanerequires read and writepermission for these files, and for the directory within that they reside.

[Tip]Tip

The server (i.e. Yule) only needs readaccess to this directory and the files therein. This allows to chownthe data directory to another user, as long as Yulehas read access.

[Tip]Tip

Writing to the data directory is not performed by the beltanePHP process, but by helper programs ( beltane_cp, beltane_log, beltane_signand beltane_update). This allows to perform write access notwith the privileges of the webserver / PHP process, but with the privileges of some other user (by making these helper programs SUID 'user', where 'user' should notbe 'root').

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

The recommended setup would be as follows:

Users

Create a group (say, samhain) and two users (say, yule, and beltane) with that group.

Data directory

Now make beltanethe owner of the yuledata directory (usually /var/lib/yule), as well as of all the client configuration and database files therein. Make the directory, and the aforementioned files, group readablefor the group samhain.

If you use mod_php

The beltanePHP scripts will be executed with the UID/GID of the web server. To get write access to the yuledata directory, you should make the helper executables ( beltane_updateet al.) suid beltane. To do so, you need to chown beltane:samhain beltane_update, and set the suid and sgid bits with chmod 6755 beltane_update(and likewise for the other helper executables):

                bash$
                chown beltane:samhain
                beltane_update
                bash$
                chmod 6755
                beltane_update
              

Using the configureoption --enable-postinstall=suidwill set the helper programs suid/sgid to the current owner and group of the yuledata directory upon installation.

If you use CGI php

There are two possibilities:

a) If you use the Apache suexecwrapper to execute BeltanesPHP scripts, you can have them executed as user beltane.

b) If you don't want to use suexec, the PHP scripts are executed with the UID of the webserver. This is the same case as with mod_php(see above).

Note that the data directory must be readablefor the PHP process. You may want to include Apachein the samhaingroup, if you don't use suexec.

2.8.5. Using an SSH Tunnel

For improved security, you may want to access the webserver on the machine running yulevia a secure SSH tunnel only. This can be done in the following way:

On the machine where yuleis running, change the apacheconfig file ( httpd.conf) as follows: change BindAddress *to BindAddress 127.0.0.1, and Listento Listen 127.0.0.1:80. Afterwards, restart apache— it will now honour only requests from localhost.

Create an SSH tunnel from your machine to the server with:

          bash$
          ssh -C -L 2080:127.0.0.1:80 
          Server_Address
        

In your browser, type the address http://localhost:2080

2.9. Backups

Beltaneuses four C programs: beltane_cp, beltane_update, beltane_sign, and beltane_logto perform actions that require write permission to data in the yuledata directory or to Beltanesglobal log file. These programs can only be used by root and optionally by a single other user (see Section 2.3, “Configure”.

beltane_cpwill 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 yuledata directory. All calls to beltane_cpare logged in the Beltanelog 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_updatewill update client file signature databases according to its command line arguments. All calls to beltane_updateare logged in the Beltanelog 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 .logwill 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.lastis written, which is used in the undooption that is displayed after performing an update.

beltane_signwill clearsign a file. It is used with Beltanessigning function to re-sign updated files.

beltane_logwill write an entry to the global log file. It is mainly used to track user login/logouts.

2.10. Samhain configuration

id="samhainconf" >

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:

[Tip]CAVEAT

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