3. Functions

After logging in, the main window will show up, which is subdivided into four panels.

3.1. The menu panel

In the upper part is the menu panel with a menu row at the top and a row of buttons for fast access to some functions.

Also, the current status of the server (running/stopped/unknown) will be indicated. This information is gained by reading the servers PID from the pid file and probing for the existence of the process. The status line doubles as a link to the HTML status page written by the server.

In addition, the username, privilege level, and remaining time until idle logout are shown.

3.1.1. Buttons

Refresh

Refresh all panels.

Signatures

Check PGP signatures on configuration files and baseline file signature databases, and renew them after running an update (see Section 3.3.3).

Select all

Select all currently displayed messages.

Update

For all selected messages, the file signature database of the respective client will be updated, and the message be marked as confirmed. Messages for which file signature updates are not applicable (e.g. client startup messages) are handled gracefully.

Bulk Update

Enter the dialog for bulk updates (see Section 3.3.2).

Confirm

The record in the SQL database will get acknowleged, but the file signature database will not get updated. For messages that do not refer to filesystem changes, or if you don't want to update the database..

All Clients

View messages for all clients.

3.1.2. Menu

File -> Refresh

Refresh all panels (same as 'Refresh' button).

File -> Logout

Exit the application, and destroy the PHP session.

Messages -> Select all

Select all displayed messages.

Messages -> Reset

De-select all selected messages.

Messages -> All Clients

View messages for all clients (same as 'All Clients' button).

Updates -> Bulk Update

Enter the dialog for bulk updates (see Section 3.3.2). Same as 'Bulk Update' button.

Updates -> Update

For all selected messages, the file signature database of the respective client will be updated, and the message be marked as confirmed. Messages for which file signature updates are not applicable (e.g. client startup messages) are handled gracefully. Same as 'Update' button.

Updates -> Confirm

The record in the SQL database will get acknowleged, but the file signature database will not get updated. For messages that do not refer to filesystem changes, or if you don't want to update the database. Same as 'confirm' button.

Tools -> Server status

Display the HTML status page written by the server. Same as 'Server status' button.

Tools -> Signatures

Check PGP signatures on configuration files and baseline file signature databases, and renew them after running an update (see Section 3.3.3). Same as 'Signatures' button.

Tools -> Search database

Search the SQL database for entries.

Reload -> Show pending commands

Show the commands queued by the server to be sent to clients. As clients do not listen on the network, commands can only be sent when the client itself connects (e.g. to deliver a timestamp message).

Reload -> Reload all clients

Tell the server to send a reload command (to reload the configuration) to all clients. As clients do not listen on the network, commands can only be sent when the client itself connects (e.g. to deliver a timestamp message).

Reload -> Cancel reloads

Tell the server to cancel all pending commands for clients.

Reload -> Run scan on all clients

Tell the server to send a scan command (to perform a file system check) to all clients. As clients do not listen on the network, commands can only be sent when the client itself connects (e.g. to deliver a timestamp message).

Configure

Edit Beltanes configuration file entries.

Help -> Contents

Show this help.

Help -> Performance

Show some performance data that might be helpful to discover problems.

Help -> About

Show the version of beltane.

3.2. The Clients panel

In the Clients panel, Beltane shows the list of currently recognized clients. Left in the title bar, you will find the Add function to add a new client entry.

The status of any client is indicated in the leftmost column of the client list. Possible values are:

Unknown

The client status is unknown, possibly because it has not connected to the server since server startup.

Active

The client is running.

Dead

The client has exited, or has not reported within the timeout limit configured in the server configuration. You need to have clients send timestamp messages for this to work properly.

Uninstalled

The client has an entry in the client database, but is marked as uninstalled.

NoteNOTE
 

Status information is taken from the server (yule) HTML status page. You need yule 1.7.8 or later for this feature.

The severity of the most severe new message of any client is indicated by a coloured box to the left of the client name (purple = Alert, red = Critical, orange = Error, yellow = Warning, green = Info, white = None). This status corresponds to the most severe new message for the corresponding client. Filtered messages are not taken into account (see also Section 3.3).

TipTip
 

Left click on the colored box to the left of the client name will show all messages for this client (only) in the messages panel.

Left click on a client name will bring up a menu with the following items:

Edit

Edit the entry for this client.

Delete

Delete the entry for this client.

Details

Show the entry for this client.

Messages

Show all new messages for this client.

ThisMsg

Show the message corresponding to the status indicator. The message will be shown in the lower right panel. In the title bar, a function Acknowledge is provided.

Bulk Update

Enter the dialog for bulk updates (see Section 3.3.2).

Reload

Submit a reload command for this client to the yule server. The server will store the command and will issue it to the client next time the client connects (e.g. to deliver the regular timestamp message). The client will then reload its configuration, exactly as if it receives a SIGHUP signal.

NoteNOTE
 

You need yule 1.8.0 or later for this feature. In the yule configuration, you need to enable the server's unix domain socket, and to configure the user (UID) who can send commands to the server. In the Beltane configuration, you need to enter the path to the yulectl command that is part of the samhain/yule distribution and allows to send commands to the server socket.

As of yule 1.8.12, it is possible to use password-based authentication on the server command socket (see the samhain manual), which allows to use this feature also on systems that cannot pass user credentials via a unix domain socket.

Scan

Submit a scan command for this client to the yule server. The server will store the command and will issue it to the client next time the client connects (e.g. to deliver the regular timestamp message). The client will then perform a file integrity check.

Only supported for samhain client version 2.5.1 and above. Also see note above (on 'Reload').

Edit config

This allows to edit the client's configuration file. If you are using signed configuration files, you can use the Sign function in the upper panel to renew the signature. You may want to use the Reload function (see above) to force the client to reload the modified configuration.

TipTip
 

You can close the context menu by mousing over it and then off of it.

3.2.1. The Client database

Beltane requires an up-to-date database of installed clients, and allows you to interactively edit this database, if needed. This database is a flat file in XML format, named yulerc.install.db, and located in the profiles/ subdirectory of the yule data directory. For each client, this file has the following entries:

Hostname

The FQDN (or IP number, if yule cannot resolve the IP) of the client host. This the only entry that is currently used by beltane.

Group

The group to which the client belongs to. This is used to determine whether a user beltane can view that particular client (as well as reports from that client) or not. See also Section 6 for the access rules that are applied.

Operating system

The OS of the client host (e.g. redhatlinux_i386, suselinux_i386, debianlinux_i386, solaris).

Installation date

Date the samhain client was installed on the host.

Installation status

The status of the samhain client installation (e.g. installed/uninstalled).

Installation name

The name under which the samhain client was installed on the host. (Samhain fully supports re-naming to some arbitrary name, including re-naming directories, pid file, etc.).

Installation prefix

The argument to the --prefix option of the configure script for that client. Basically, this, together with the install name, should allow to determine the name and location of the samhain executable on the client host.

Installation version

The version of samhain installed on this client.

TipWhat should I fill in?
 

If you are using the deploy.sh command delivered with samhain in order to deploy clients to remote hosts, the client database will already exist, as deploy.sh uses it to log the performed installations.

Otherwise, you will need to edit/create the list of installed clients manually. In that case, the only relevant entry is the hostname.

If the file does not exist on startup, Beltane will create a dummy file. You need to create then a valid entry, before you can delete the DUMMY entry.

WarningWarning
 

Beltane will need the FQDN of clients in the client database (or the IP number, if clients are known to yule by IP number only). In particular, Beltane will not function properly if you have only the hostname in the client database, and yule is configured to strip the domain.

3.3. The Messages panel

The Messages panel displays new messages, i.e. messages not yet acknowledged by the user. For each message, a status icon, the database index, severity, hostname, the message text, and (if applicable) the file path is shown. Each message can be selected with a select box to the left.

By default, messages are sorted newest first. There are three configuration options which are relevant for the display of messages: Displayed messages is an optional upper limit on the number of messages to display. With Filters you can filter messages that you do not want to see. Messages matching the regular expression will not be displayed. View server messages is a boolean option; if TRUE, also messages from the server itself (rather than only messages received from clients) will be shown.

TipTip
 

On-the-fly sorting is possible by clicking on the column headers. Clicking a second time on the same header will revert the sort order.

TipTip
 

If there are more messages than displayed in the panel, you can page using the ">" and "<" link(s) at the left side of the table header.

Clicking on the database index will display all details of the respective message. Clicking on the host name will alter the message panel to show messages for that host only (use All Clients to reset).

3.3.1. Message details

When the details of a log message are shown in the lower right panel, you can click on Update next to the file path. This will trigger the update of the file signature database, and also acknowledge the corresponding entry in the SQL database.

If you click on Confirm instead, the record in the SQL database will get acknowleged, but the file signature database will not get updated (thus after a re-start of the samhain client, you will get a message for that file again).

3.3.2. Bulk updates

Bulk Update requires PHP >= 4.3.0.

Rather than reviewing client messages, and selecting them manually for update, it is possible to perform a 'bulk update' for all client messages according to some criteria. If you click on Bulk Update, you will enter a dialog to define these criteria.

Currently supported are: Host — the hostname of the client, interpreted as Perl regular expression; Path — the path of the file(s), interpreted as a Perl regular expression; File list — a list of files, one per line, for which you want to perform updates; Modification time — lower and/or upper limits on the modification time of files; Log time — lower and/or upper limits on the time when the message was logged.

If you specify more than one criterium, only files that match all specified criteria are considered for update.

TipRegular expressions for host names and paths
 

To match a set of hosts, or a set of paths, you can supply a Perl-style regular expression for the Host or Path field. Please note that Perl regular expressions must be enclosed by matching delimiters, e.g. #pattern#, or /pattern/.

On Linux, see man perlre for details on Perl regular expressions. You may also have a look at the PHP manual for an overview of Perl-Compatible Regular Expressions (PCRE): http://php.net/manual/en/pcre.pattern.php

3.3.2.1. Checksums in the file list

A File list may include checksums for the listed files. In that case, the checksum must come first, followed by space, followed by the file path. The checksum must be the same as used by samhain (by default TIGER192, but MD5 and SHA1 are available as runtime configuration options with the DigestAlgo=... option). If you specify checksums, you need to do this for all files in the list. For files that are not regular files (e.g. directories, devices, ...) use a single '0' (zero) as checksum.

You may notice that samhain stores all checksums as 48-digit uppercase hexadecimal values (192 bits). Checksums with less bits than the default TIGER192 checksum (MD5: 128 bits, SHA1: 160 bits) are padded with 0 on the right. You don't need to include this padding, and you can use lowercase hex - beltane will take care to normalize the checksum.

3.3.3. GnuPG Signatures

Renewing GnuPG signatures requires PHP >= 4.3.0. With earlier versions, you will only be able to check signatures.

If you have gpg signed your file signature databases, the signatures will become invalid (and, in fact, removed) when performing an update. Likewise, signatures will become invalid (and removed), if you edit a client configuration files. To fix this, a function is provided to check signatures, and renew missing ones.

Before using this function, you should configure the GPG key ID, and the GPG homedir (the directory where the keyrings are located). Clicking on Sign in the message panel will then run the signature check, and offer you to update missing signatures.

The gpg executable must be in /bin, /usr/bin, /sbin, /usr/sbin, or /usr/local/bin.

WarningWARNING
 

You will need to enter the passphrase for the GPG key. Do not use this function if you access beltane over an insecure connection.